Docs
Docs pages

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.

v1 scoring is pending. The v1 parts have not been scored against their locked plan yet, so they are marked Pending. What runs today is decided by the plan v1 (v0) results: pose and behaviour passed and are on; the rest is preview or off. This page fills in from capabilities.json when the v1 results land.

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 }
}

3. The other endpoints (1 minute)

Swap the path. Each returns one part of the same result, and all take sample.

EndpointReturnsStatus
/v1/identityEach tracked animal, and its identity id when known.Pending
/v1/pose17 body points per animal per frame.Live
/v1/behaviorWhat each animal is doing.Live
/v1/health-scoreA 0 to 100 roll-up. Null until a state reading is validated.Preview / off
/v1/forecastWhere each animal is expected to be over the next 5 s.Pending
/v1/analyzeAll 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
The hosted model is not switched on yet. The API is live, but no inference server is connected to it. A call with your own video answers 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