API reference
POST /v1/forecast Pending
For each animal and sampled frame, where its centre is expected to be over the next 5 seconds.
The forecast in the current release is a constant-velocity baseline, not a learned model. Check capability.status before you plan a robot path on it.
Request
Send a video the same way as /v1/analyze (raw bytes, or video_b64 in JSON), with the same options: species, max_seconds, start_s, step_s. Or pass sample to get a stored result of a real run with no video: nothing is metered and the response says "sample": true.
curl -s -X POST "https://vitalsbio-console.pages.dev/api/v1/forecast?sample=cow-lying" \ -H "Authorization: Bearer $VITALSBIO_API_KEY" curl -s "https://vitalsbio-console.pages.dev/api/v1/forecast?species=cattle&max_seconds=20" \ -H "Authorization: Bearer $VITALSBIO_API_KEY" -H "Content-Type: video/mp4" \ --data-binary @barn.mp4
Samples: cow-lying, dog-walk, brangus-herd, paddock, white-horses. This endpoint runs the same model call as /v1/analyze and is metered the same way, by seconds of video. If you need more than one part of the same clip, call /v1/analyze once.
Response
| Field | What it is |
|---|---|
capability | The status of this part: live (passed its locked test), preview, pending or off. Read it before you rely on the numbers. |
sample | true when the answer is a stored result, not a run on your video. |
animals[].available | false when the result holds no forecast for this animal (too few frames). |
animals[].frames[].forecast.horizons_s | How far ahead each point is, in seconds. |
animals[].frames[].forecast.centre | The expected centre [x, y] in pixels, one per horizon. |
animals[].frames[].forecast (other fields) | A 1-sigma radius in pixels and an intent word, as in the result schema. |
usage.video_seconds | Seconds of video metered for this call. Also in the X-Vitals-Video-Seconds header. |
request_id, api_version | Also in the X-Request-Id and Vitals-Version headers. |
This is the real answer for sample=cow-lying, cut short:
{
"object": "forecast",
"request_id": "req_Lr0d1sY2rE9q",
"api_version": "2026-11-21",
"schema_version": "biomodel-v0.1",
"capability": {
"id": "forecast",
"name": "Forecast",
"status": "pending",
"mode": "preview",
"label": "Pending"
},
"sample": true,
"video": {
"fps": 25,
"width": 1920,
"height": 1080,
"n_frames": 689,
"step_s": 0.2
},
"model": {
"name": "vitals-biomodel",
"version": "biomodel-v0.1"
},
"animals": [
{
"track_id": 1,
"species": "cattle",
"available": true,
"frames": [
{
"t_s": 0.2,
"frame_index": 5,
"forecast": {
"horizons_s": [0.2, 0.4, 0.6],
"centre": [
[352.9, 669.6],
[351.2, 668.9],
[350.2, 671.3]
],
"centre_sigma": [25, 37.7, 51.7],
"keypoints": null,
"keypoints_sigma": null,
"intent": "staying",
"model": "learned forecaster (bio-forecast-v0)"
}
}
]
}
],
"usage": {
"video_seconds": 0
}
}
Errors, limits and headers are the same on every endpoint: see errors and rate limits. For a long video or a camera, see streaming.