HTTP API reference
Every route mozo start serves. The guide is HTTP server; each model's page
says which of these parameters it takes. A running server also serves this as an OpenAPI document
at /docs.
Errors are JSON, {"detail": "..."}, with a message that says what to do:
| Status | Meaning |
|---|---|
400 |
The request is wrong: not an image, a required prompt missing, a parameter out of range or of the wrong kind for this model. |
404 |
No such model on this server, or no image held for a ?sha256=. The detail lists what is served. |
500 |
The model failed to load or to run. |
501 |
The model has no such route, such as /predict on a text-embedding model or /encode on a detector. |
POST /predict/{family}/{variant}
Run a model on one image. The image is a multipart upload named file; everything else is a query
parameter. Repeat a parameter to give several values.
| Parameter | For | Description |
|---|---|---|
file |
all | The image. Leave it out only when naming a prepared image by sha256. |
threshold |
detectors, prompted models | Confidence floor. Omitted, the family's own default applies. |
labels |
detectors | Comma-separated class names replacing the model's own, such as hardhat,vest. |
text |
prompted models | A phrase to look for. Repeat it for several: ?text=car&text=person. Not comma-separated, so a phrase may contain a comma. |
point |
SAM 2, EdgeTAM, SAM 3 | A click as x,y in the image's pixels. Each needs a label. On SAM 3, a click or text, not both. |
label |
SAM 2, EdgeTAM, SAM 3 | 1 to include the matching point, 0 to exclude it. One per point, in order. No default. |
box |
SAM 2, EdgeTAM, SAM 3, ViTPose, Moebius | A box as x1,y1,x2,y2. The segmenters segment it, ViTPose finds the joints of the person in it, Moebius removes it. |
name |
SAM 2, EdgeTAM, SAM 3 | What to call what you pointed at. Omitted, class_name is null. |
multimask |
SAM 2, EdgeTAM, SAM 3 | true (default) for three candidate masks ranked by predicted IoU, false for one. |
seed |
Moebius | Which sample to draw. Default 0. |
sha256 |
SAM 2, EdgeTAM, SAM 3, OWLv2 | The sha256 of an image this server holds from /prepare. Send it instead of file. |
Responses by task:
| Models | Response |
|---|---|
| Detection, segmentation, keypoints, detection from words, click segmentation, OCR | application/json: a list of detections with every PixelFlow field. |
| CLIP, SigLIP 2 | application/json: a list of {class_id, class_name, confidence, metadata}. |
| Depth Anything V2 | image/png, 16-bit. Headers x-depth-unit (metres or none), x-depth-min and x-depth-max: depth = min + png / 65535 * (max - min). |
| BEN2 | image/png: the photograph as RGBA, background transparent. |
| Moebius | image/png: the photograph with every box painted out. |
A prepared image not held by this server (another worker, a restart, or dropped to stay within
MOZO_PREPARED_MB) answers 404. Send the file again with the same sha256 and it is kept for the
requests after.
POST /encode/{family}/{variant}
Return vectors instead of an answer. For CLIP, SigLIP 2 and Granite Embedding R2.
| Parameter | Description |
|---|---|
file |
An image to embed. Repeat for several. CLIP and SigLIP 2. |
text |
A phrase or text to embed, as a query parameter. Repeat for several. |
Images or text in one call, not both. Returns:
{"model": "clip/base", "revision": "2026-08-23", "dim": 512, "embeddings": [[-0.00398, -0.00317, ...]]}embeddings has one row per input, in order, each L2-normalised. Keep model and revision with
stored vectors: a vector only compares with vectors from the same weights.
POST /prepare/{family}/{variant}
Encode an image ahead of its prompts and keep it, for SAM 2, EdgeTAM, SAM 3 and OWLv2. Send the
image as file. Returns {"sha256": "..."}, the hash of the file's bytes; later /predict
requests send ?sha256= instead of the file. Memory for kept images is limited by
MOZO_PREPARED_MB, 512 MB by default, and the least recently used is dropped first.
GET /
Health: {"status": "ok", "version": "1.10.0", "loaded_models": [...]}.
GET /models
Every model this server offers, as {family: entry}, without loading anything. An entry has:
| Field | Description |
|---|---|
task_type |
Such as object_detection or promptable_segmentation. |
description |
What the family does. |
variants |
The variants this server offers. |
licenses |
{variant: licence}. |
prompted |
Whether /predict needs text. |
boxed |
Whether it takes boxes as input rather than finding them (ViTPose, Moebius). |
clicks |
Whether it takes point and label. |
prepares |
Whether /prepare and sha256 work for it. |
encodes |
What /encode takes for it: ["image", "text"], ["text"], or []. |
GET /models/loaded
The models in memory now: {"models": ["rfdetr/nano", ...]}.
GET /test-ui
A browser page to try any model on an image.
GET /static/example.jpg
The photograph these docs use in their examples, five people around a table. The test page loads it, and it is a quick way to get an image to try a route on.
GET /docs
The generated OpenAPI reference for every route.
GET /workflow
The workflow editor. See Build a workflow in the editor.
GET /workflow/nodes
Every node a workflow can use, as {"nodes": [...], "process": true}. process says whether
/workflow/process is offered.
POST /workflow/validate
Check a workflow without running it. Form field workflow, the document as JSON. Returns
{"valid": true, "order": [...], "terminals": [...]}, or {"valid": false, "error": "..."} with
the reason.
POST /workflow/run
Run a workflow once.
| Form field | Default | Description |
|---|---|---|
workflow |
The workflow document, as JSON. | |
inputs |
{} |
Parameter overrides, as a JSON object, keyed as run() takes them. |
include |
terminals |
terminals for the end nodes' outputs, all for every node's. |
file |
An image or video to run on, instead of the one the workflow names. |
Returns {"results": {node id: output}, "terminals": [...]}. Images come back encoded, so ask for
all only when you need the intermediates: encoding every node's output costs more than running a
small workflow.
POST /workflow/stream
As /workflow/run, but answers with server-sent events: one as each node starts and another as it
finishes, with its output.
POST /workflow/process
Run a workflow over everything its source produces, such as every frame of a video, reporting
progress as server-sent events. Form fields workflow, inputs and file as for run, plus
preview, a node id to send a thumbnail of with each item. Each event carries item, the number
done, of, how many the source expects, and frame and time, where the item sits in the file.
Not offered when the router was mounted with process=False.