Docs
Docs pages

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.

Not on PyPI or npm yet. Install from the repository folder: pip install ./sdk/python or npm install ./sdk/js.

Methods

PythonJavaScriptCalls
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()sameGET /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

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.