API Reference
visynx.Visynx
Entry point to the Visynx inference API.
vf = Visynx(api_key="vf_...") # or set VISYNX_API_KEY model = vf.model("shelf-scanner/3") result = model.predict("shelf.jpg", confidence=0.4)
load_model(source, **kwargs)
Load a model you downloaded and run it here — see
:func:visynx.load_model, which this is the client-shaped name for.
Nothing about it is authenticated: the account, the plan and the model's
owner were all checked when :meth:Model.download fetched the file.
model(ref=None, *, train_name=None, version=None, format='auto')
The trained model to run.
Name it the way the platform names it — your project and its training version — either as one handle or as two arguments:
vf.model("shelf-scanner/3") vf.model(train_name="shelf-scanner", version=3)
A raw "provider/job_id" is also accepted so scripts holding a job id
keep working (and it skips the model-list round trip entirely).
format picks the runtime every :meth:Model.predict call on the
returned model runs on — "auto" (the default, and the cheapest per
call), "onnx_fp16", "onnx_fp32", "edge" or "native":
vf.model(train_name="shelf-scanner", version=3, format="edge")
models(refresh=False)
Every trained model on this account that is ready to run.
Cached on the instance; pass refresh=True after training something new.
visynx.Model
dataclass
A trained model. Get one from :meth:Visynx.model, not by constructing it.
labels
property
Class names the model predicts, in class-id order.
Read from the weights themselves, so they stay correct even if the source dataset's classes were renamed after training.
download(path='.', *, format='native')
Download this model's weights, and return the file that was written.
model.download(path="./models/shelf-scanner") PosixPath('models/shelf-scanner/best.pt')
Taking a model off the platform is a Professional / Enterprise
feature — on any other plan this raises :class:PlanRequiredError, and
the check is the server's, not this method's. Hosted
:meth:predict works on every plan and needs no download.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
Any
|
where to put it. A directory (the usual case) is created and the model is written inside it under the platform's own filename. |
'.'
|
format
|
str
|
|
'native'
|
Load what you downloaded with :func:visynx.load_model.
predict(source, *, confidence=0.0, segment=False, depth=False, format=None)
Run the model on an image.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
source
|
Any
|
image path, directory of images, bytes, open binary file, PIL image, or numpy array. |
required |
confidence
|
float
|
drop detections scoring below this (0-1). |
0.0
|
segment
|
bool
|
refine each detected box into an instance polygon with SAM2. |
False
|
depth
|
bool
|
also return a monocular depth map for the image. |
False
|
format
|
str | None
|
the runtime to run on — |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
A |
Result | list
|
class: |
A call on the checkpoint or the full-precision graph spends 1 Vision
Credit; the optimised runtimes ("onnx_fp16", "edge") spend 2.
"auto" is billed for whichever it ends up running. segment and
depth each run a second model on the GPU and cost extra on top — see
the pricing page. You are only charged once the inference succeeds, and a
retried call is billed once.
visynx.load_model(source, *, device='auto', labels=None, variant=None)
Load a model you have downloaded, and run it here.
model.download(path="./models/shelf-scanner") # Professional / Enterprise local = visynx.load_model("./models/shelf-scanner") local.predict("shelf.jpg")
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
source
|
the file exactly as you downloaded it, or the directory you downloaded it into. |
required | |
device
|
str
|
where to run it. |
'auto'
|
labels
|
class names, in class-id order. Only needed for a model that was exported without them; otherwise they are read from the file. |
None
|
|
variant
|
str | None
|
reserved for checkpoints that can't state their own size. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
A |
LocalModel
|
class: |
visynx.LocalModel
A model running on this machine. Get one from :func:load.
device
property
Where this model is running: "auto", "cpu" or "gpu".
labels
property
Class names the model predicts, in class-id order (empty if the file
carries none — pass labels= to :func:load for those).
providers
property
What the graph actually loaded on, in the runtime's own names — which is not always what was asked for: a GPU provider that is installed but can't initialise (a cuDNN the runtime doesn't match, say) is dropped and the model runs on the CPU. Empty for a checkpoint, which has no graph session. Use it to check a model got the device you meant it to.
predict(source, *, confidence=0.25, iou=0.7)
Run the model on an image.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
source
|
Any
|
image path, directory of images, bytes, open binary file, PIL image, or numpy array — the same inputs the hosted client takes. |
required |
confidence
|
float
|
drop predictions scoring below this (0-1). |
0.25
|
iou
|
float
|
overlap above which two predictions of one class are merged. The defaults match what the platform itself runs, so a local result and a hosted one agree. |
0.7
|
Returns:
| Name | Type | Description |
|---|---|---|
A |
Result | list
|
class: |
Result | list
|
is a directory. |
visynx.Result
What one image came back as.
Iterate it for detections, call :meth:json for the raw payload, or
:meth:plot / :meth:save to see it.
depth_image
property
The depth map as a colourised PIL image, or None if depth wasn't requested.
image
property
The image this result is about, as a PIL image.
json()
The raw API response, unmodified.
plot()
Draw the predictions onto the source image and return a PIL image.
save(path)
Write :meth:plot's annotated image to path. Returns the path.
visynx.Detection
dataclass
One predicted object. box is [x1, y1, x2, y2] in absolute pixels.
Classification models return detections with no box; segmentation models
add polygons (flat [x1, y1, x2, y2, ...] per instance); pose models
add keypoints ([[x, y, visibility], ...]).
visynx.open_camera(source=0, *, width=1280, height=720, fps=30)
Open csi://N, usb://N (or a bare index), or any URL/file OpenCV reads.
visynx.setup(kind='all')
Install what a checkpoint needs in order to run on this machine.
Portable (.onnx) exports never need this — pip install "visynx[local]"
is enough for those. Also available as python -m visynx setup.
Errors
Every error subclasses VisynxError.
visynx.VisynxError
Bases: Exception
Base class for every error raised by visynx.
visynx.AuthenticationError
Bases: VisynxError
401 — the API key is missing, invalid, or revoked.
visynx.PermissionDeniedError
Bases: VisynxError
403 — email unverified, account deactivated, or the key's IP allowlist rejected you.
visynx.InsufficientCreditsError
Bases: VisynxError
402 — out of Vision Credits. Not a transient error; top up.
visynx.PlanRequiredError
Bases: VisynxError
402 — your plan does not include this. Downloading a trained model is a Professional/Enterprise feature; hosted inference is on every plan.
visynx.ModelNotFoundError
Bases: VisynxError
404 — no such model, or it isn't yours.
visynx.PayloadTooLargeError
Bases: VisynxError
413 — the image exceeds the inference upload limit.
visynx.RateLimitError
Bases: VisynxError
429 — rate limited, and the retries were exhausted.
visynx.MaintenanceError
Bases: VisynxError
503 — the platform is in maintenance mode.