SDKs
API clients: Python and JavaScript
Thin, typed clients for the hosted API. No dependencies. They retry for you, cut video into segments, and raise errors that carry the request id.
pip install ./sdk/python or npm install ./sdk/js.Methods
| Python | JavaScript | Calls |
|---|---|---|
client.analyze(video, ...) | client.analyze({ video, ... }) | POST /v1/analyze |
client.identity(...) | client.identity({...}) | POST /v1/identity |
client.pose(...) | client.pose({...}) | POST /v1/pose |
client.behavior(...) | client.behavior({...}) | POST /v1/behavior |
client.health_score(...) | client.healthScore({...}) | POST /v1/health-score |
client.forecast(...) | client.forecast({...}) | POST /v1/forecast |
client.stream(source, ...) | client.stream(segments, {...}) | one call per segment, see streaming |
client.me() | client.me() | GET /v1/me: plan, limits, minutes left |
client.capabilities(), client.health() | same | GET /v1/capabilities, GET /v1/health |
Pass a video (a path, bytes or a file in Python; bytes or a Blob in JavaScript) or sample, plus species, max_seconds, start_s, step_s.
Set up
VitalsBio(api_key=None, base_url=None, timeout=320, max_retries=3, backoff=0.5, max_backoff=30) # Python
new VitalsBio({ apiKey, baseUrl, timeoutMs: 320000, maxRetries: 3, backoffMs: 500, maxBackoffMs: 30000 }) // JavaScript
With nothing passed, the key comes from VITALSBIO_API_KEY and the address from VITALSBIO_BASE_URL (default https://vitalsbio-console.pages.dev/api).
Retries
- Retried:
429 rate_limited, 500, 502, 503, 504 and connection errors, up tomax_retriestimes. - The wait doubles each time, with jitter, up to 30 s. When the API sends
Retry-After, the client waits that long. - Not retried: 400s, auth errors, and
monthly_quota_exceededorkey_cap_exceeded(they will not pass until the 1st).
Errors
from vitalsbio import VitalsBio, RateLimitError, QuotaExceededError, InferenceUnavailableError, APIError
try:
r = VitalsBio().pose("clip.mp4")
except InferenceUnavailableError as e: # no backend connected; nothing was metered
print("try later", e.request_id)
except QuotaExceededError as e:
print(e.message)
except APIError as e:
print(e.status, e.code, e.param, e.request_id, e.doc_url)
JavaScript has the same classes, with requestId, docUrl and retryAfter.
Types
Python: vitalsbio.types has a TypedDict for every response, and the package ships py.typed. JavaScript: src/index.d.ts types every method, so client.pose(...) returns a PoseResponse. Responses also carry the request id and metered seconds: r.request_id and r.video_seconds in Python, r.requestId and r.videoSeconds in JavaScript.
Examples that run
python sdk/python/examples/quickstart.py node sdk/js/examples/quickstart.mjs python sdk/python/examples/stream_video.py barn.mp4 node sdk/js/examples/stream-video.mjs barn.mp4
With no account, start the local API first: node console/tools/local_api.mjs --stub-backend. With --stub-backend, video uploads answer with a stored real result, marked as coming from the stand-in; it is not a live model run.
The API is also described in OpenAPI 3.1, if you want to generate a client for another language.