visynx

Run your VisionForge computer-vision models from Python.

Train a model in VisionForge, grab an API key, and you are three lines from predictions — detection, segmentation, pose, classification, and semantic segmentation, all through one call.

pip install visynx

Quickstart

from visynx import Visynx

vf = Visynx(api_key="vf_...")          # or set VISYNX_API_KEY
model = vf.model("shelf-scanner/3")    # your project name and version

result = model.predict("shelf.jpg", confidence=0.4)

for d in result:
    print(d.class_name, round(d.confidence, 2), d.box)

result.save("annotated.jpg")

bottle 0.94 [412.0, 118.5, 501.2, 388.0]
bottle 0.91 [502.6, 121.0, 590.4, 390.7]
can    0.78 [604.1, 210.3, 664.9, 372.2]

visynx pulls in only requests and Pillow. No OpenCV, no numpy, no torch — the models run on VisionForge's GPUs, not yours.

Find your models

for m in vf.models():
    print(m.slug, m.provider, m.display_name)
# shelf-scanner/3   yolo     Shelf Scanner v3
# defect-seg/1      rfdetr   Defect Seg v1

"shelf-scanner/3" is the model's slug — your project name and its training version, the same name you see in the app. A raw "yolo/<job_id>" also works and skips the lookup.

What you get back

predict() returns a Result: iterate it for detections, or reach for the raw API payload with .json().

result = model.predict("shelf.jpg")

len(result)              # 3
result.detections[0]     # Detection('bottle', 0.94)
result.json()            # the raw API response, untouched

result.plot()            # a PIL image with boxes drawn on
result.save("out.jpg")   # ...written to disk

Each Detection carries class_id, class_name, confidence, and box ([x1, y1, x2, y2] in absolute pixels). Segmentation models add polygons; pose models add keypoints.

Anything image-shaped works

model.predict("shelf.jpg")                  # a path
model.predict("frames/")                    # a directory -> list of Results
model.predict(open("shelf.jpg", "rb"))      # an open file
model.predict(pil_image)                    # a PIL image
model.predict(numpy_array)                  # a numpy array (from OpenCV, say)

Beyond boxes

Two flags the hosted GPUs do for you, with nothing extra to install. Each runs a second model, so each costs extra credits:

# Turn every detected box into a precise instance polygon with SAM 2
result = model.predict("shelf.jpg", segment=True)
result.detections[0].polygons

# Add a monocular depth map, and a relative distance per detection
result = model.predict("shelf.jpg", depth=True)
result.detections[0].depth_median      # 0-1, higher is closer
result.depth_image.save("depth.png")

Semantic-segmentation models return a dense mask instead of boxes:

result = model.predict("road.jpg")
result.semantic["legend"]     # [{'class_id': 1, 'class_name': 'road', ...}]
result.save("mask.jpg")       # the mask, blended over your image

Get an API key

In VisionForge, go to Settings → API Keys, create a key, and copy the secret — it is shown once. Keys start with vf_, never expire, and can be locked to specific IPs or CIDR ranges. Keep it out of source control:

vf = Visynx()                      # reads VISYNX_API_KEY

A plain predict() call spends 1 Vision Credit; segment=True and depth=True each add a surcharge for the extra model they run. You are charged only after the inference succeeds — a failed call is free — and a call retried after a 429 is billed once, not twice.

Some endpoints are deliberately not reachable with an API key: batch prediction over a whole dataset, live-camera inference, workflow runs, and the AI-labelling tools (SAM/DINO/box-prompt). Those run from the VisionForge app with a signed-in session. Calling them with a key returns PermissionDeniedError.

Errors

Every failure is a typed exception, and it quotes the response's X-Request-ID when the server sent one — include it if you contact support. (Authentication failures are rejected before that header is assigned, so 401s carry none.)

429s are retried automatically, honouring the server's Retry-After. All of these subclass VisynxError, so one except VisynxError catches everything.

Self-hosting

Point the client at your own deployment:

vf = Visynx(api_key="vf_...", api_url="https://visionforge.internal/api")

or set VISYNX_API_URL.

License

MIT