Docs
Docs pages

API reference

Streaming video

For a long file or a live camera, send short segments one after another. The clients cut the video, send a few segments at a time, and hand you results in order with stream times.

What this is and is not. Each segment is its own API call. The API does not hold a connection open on a camera; that kind of live stream is not built. A result arrives one segment length plus the model's run time after the moment it shows.

How it works

Add three options to any model endpoint. They are echoed back under stream.

OptionWhat it is
stream_idYour name for the stream: 1 to 64 letters, digits, or _ . : -
segment_index0, 1, 2 and so on.
offset_sWhere this segment starts in the stream, in seconds.
curl -s "https://vitalsbio-console.pages.dev/api/v1/behavior?stream_id=barn-cam-1&segment_index=3&offset_s=30" \
  -H "Authorization: Bearer $VITALSBIO_API_KEY" -H "Content-Type: video/mp4" --data-binary @seg-000003.mp4

Python

from vitalsbio import VitalsBio

client = VitalsBio()
# a file or anything ffmpeg can read, such as rtsp://camera/1 (needs ffmpeg on PATH)
for seg in client.stream("barn.mp4", endpoint="behavior", segment_seconds=10, species="cattle"):
    print(seg["stream"]["segment_index"], [(a["track_id"], a["top"]) for a in seg["animals"]])

# or hand it ready clips: paths, bytes or open files
for seg in client.stream(["a.mp4", "b.mp4"], endpoint="pose", segment_seconds=10):
    ...

JavaScript

import { VitalsBio, recordSegments } from "@vitalsbio/sdk";
import { segmentFile } from "@vitalsbio/sdk/node";      // Node, needs ffmpeg

const client = new VitalsBio();
for await (const seg of client.stream(segmentFile("barn.mp4", 10), { endpoint: "behavior", segmentSeconds: 10 })) {
  console.log(seg.stream.segment_index, seg.animals.map((a) => a.top));
}

// in a browser, from a camera (send through your own server so the key stays private)
// for await (const clip of recordSegments(mediaStream, 10)) { ... }

Things to know