Get started
Quickstart
Vitals Bio takes a video and tells you, for every animal in it, who is who, where its body points are, what it is doing, and where it is heading. This page takes you from nothing to a first result in under five minutes. You don't need a video for the first call.
1. Get a key (1 minute)
Create an account, open API keys and create one. It starts with vb_ and is shown once.
export VITALSBIO_API_KEY=vb_...
2. Make a call (1 minute)
Ask for the behaviour of the animals in a stored sample clip. sample returns the saved result of a real model run, so it works with no video and counts no minutes.
curl -s -X POST "https://vitalsbio-console.pages.dev/api/v1/behavior?sample=cow-lying" \ -H "Authorization: Bearer $VITALSBIO_API_KEY"
You get one JSON document. The parts to look at first:
{
"object": "behavior",
"request_id": "req_Lr0d1sY2rE9q",
"capability": { "id": "behaviour", "status": "live" },
"sample": true,
"animals": [
{ "track_id": 1, "species": "cattle", "top": "lying",
"share": { "lying": 0.963, "standing": 0.037 },
"frames": [ { "t_s": 0, "behaviour": { "lying": 0.893, "standing": 0.107 } } ] }
],
"usage": { "video_seconds": 0 }
}
capability.statustells you how far to trust this part:livepassed its locked test,pendingandpreviewhave not,offis not measured.sample: truemeans a stored result, not a run on your video.request_idis what to send us if something looks wrong.
3. The other endpoints (1 minute)
Swap the path. Each returns one part of the same result, and all take sample.
| Endpoint | Returns | Status |
|---|---|---|
/v1/identity | Each tracked animal, and its identity id when known. | Pending |
/v1/pose | 17 body points per animal per frame. | Live |
/v1/behavior | What each animal is doing. | Live |
/v1/health-score | A 0 to 100 roll-up. Null until a state reading is validated. | Preview / off |
/v1/forecast | Where each animal is expected to be over the next 5 s. | Pending |
/v1/analyze | All of it in one document. |
4. From code (2 minutes)
The clients are in the repository under sdk/. They are not on PyPI or npm yet, so install from the folder. Both have no dependencies.
Python 3.9 or later
pip install ./sdk/python
from vitalsbio import VitalsBio
client = VitalsBio() # reads VITALSBIO_API_KEY
r = client.behavior(sample="cow-lying")
for a in r["animals"]:
print(a["track_id"], a["top"], a["share"][a["top"]])
print(r.request_id, r["capability"]["status"])
JavaScript (Node 18 or later)
npm install ./sdk/js
import { VitalsBio } from "@vitalsbio/sdk";
const client = new VitalsBio(); // reads VITALSBIO_API_KEY
const r = await client.behavior({ sample: "cow-lying" });
for (const a of r.animals) console.log(a.track_id, a.top, a.share[a.top]);
console.log(r.requestId, r.capability.status);
Both retry rate limits and server errors for you, and raise typed errors with the request id. See the client reference.
5. Your own video
curl -s "https://vitalsbio-console.pages.dev/api/v1/pose?species=cattle&max_seconds=20" \ -H "Authorization: Bearer $VITALSBIO_API_KEY" \ -H "Content-Type: video/mp4" --data-binary @barn.mp4
503 inference_unavailable and counts nothing. Sample calls work today. GET https://vitalsbio-console.pages.dev/api/v1/health says "inference": "up" once a backend is connected. Until then, run the model yourself with the on-device package or the Edge SDK.When it is on: clips up to 25 MB, up to 120 s analysed per call. For a long file or a camera, see streaming.
No account? Run the API on your machine
The same API code runs locally on Node 22.5 or later, with a ready key and nothing to sign up for.
node console/tools/local_api.mjs # prints: export VITALSBIO_BASE_URL=http://127.0.0.1:8799 and export VITALSBIO_API_KEY=vb_... python sdk/python/examples/quickstart.py node sdk/js/examples/quickstart.mjs
Next
- Recipes for ranching, pets, wildlife, labs and robots.
- What is live: every part, its test, and its numbers.
- Errors and rate limits.