Docs
Docs pages

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

FieldWhat it is
capabilityThe status of this part: live (passed its locked test), preview, pending or off. Read it before you rely on the numbers.
sampletrue when the answer is a stored result, not a run on your video.
animals[].availablefalse when the result holds no forecast for this animal (too few frames).
animals[].frames[].forecast.horizons_sHow far ahead each point is, in seconds.
animals[].frames[].forecast.centreThe 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_secondsSeconds of video metered for this call. Also in the X-Vitals-Video-Seconds header.
request_id, api_versionAlso 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.