Native API
Base URL: https://<hub-host>. Every endpoint needs Authorization: Bearer <key> except the probes.
Endpoints
Section titled “Endpoints”| Method | Path | Notes |
|---|---|---|
| GET | /livez, /readyz, /healthz |
probes, no key; /healthz → {"ok","name","version","commit","uptimeSec"} |
| GET | /v1/models |
models of all online nodes in the key’s scope: id, version, name, task, state, backend, location (peer:<best node>), nodes |
| GET | /v1/models/{id} |
one model |
| POST | /v1/models/{id}/run |
image body (JPEG, PNG, WebP, GIF, BMP, HEIF, AVIF; sniffed) ≤ 10 MB → the node’s answer plus servedBy and via |
| POST | /v1/embed |
the default embedding model; adds legacy dim and embedding |
| GET | /v1/nodes |
admin or nodes:read keys: full node details; other keys see only {name, reachable, online, models} for nodes in scope |
| GET | /health |
hub summary |
Run a model
Section titled “Run a model”curl -H "Authorization: Bearer $KEY" --data-binary @photo.jpg \ https://<hub-host>/v1/models/efficientnet-lite4-int8/runimport requests
r = requests.post( "https://<hub-host>/v1/models/efficientnet-lite4-int8/run", headers={"Authorization": "Bearer sk-aigw-…"}, data=open("photo.jpg", "rb").read(), timeout=60,)r.raise_for_status()for label in r.json()["output"]["labels"]: print(label["label"], label["score"])Answer:
{ "model": {"id": "efficientnet-lite4-int8", "version": "1.0.0"}, "output": {"labels": [{"label": "…", "score": 0.0}]}, "ms": 72.0, "backend": "nnapi:mtk-mdla_shim", "servedBy": "living-room-tv", "via": "home-hub", "timings": {"decode": 0.0, "queue": 0.0, "render": 0.0, "pack": 0.0, "invoke": 22.0, "postprocess": 0.0, "total": 0.0}}Embedding models answer "output": {"embedding": [ … ]} (L2-normalised unless the manifest says otherwise).
timings (0.1 ms resolution) break down one run: decode (bytes → bitmap), queue, load (first run only),
render (crop/letterbox), pack (pixels → tensor), invoke (the accelerator), postprocess, total.
Errors
Section titled “Errors”Errors always look like {"error":{"code":"busy","message":"…"}}:
| Status | Codes |
|---|---|
| 400 | bad_request |
| 401 | unauthorized (missing or wrong key) |
| 403 | forbidden (role violation, e.g. a node key on a client endpoint) |
| 404 | not_found, model_not_found (also for models outside the key’s scope) |
| 405 | method_not_allowed (see Allow) |
| 411 / 413 / 415 | length_required, payload_too_large, unsupported_media_type |
| 429 | rate_limited (with Retry-After), quota_exceeded (daily quota), busy (queue or node slots full) |
| 500 | internal, inference_failed |
| 502 | peer_unavailable (node unreachable or gave a bad answer) |
| 503 | unavailable (no node can serve the model, or it failed to load) |
| 504 | timeout |
| 508 | loop_detected (X-Gateway-Hop above 1) |
X-Request-ID (8–64 safe characters) is accepted or generated, and returned.