Overshoot real-time vision API reference

Authenticate and discover models

Send Authorization: Bearer ovs-... with protected requests. Keep organization credentials on a trusted server unless the product is explicitly a bring-your-own-key client. GET /v1beta/models is unauthenticated and returns model records with ready or unavailable status. Pass a ready model id verbatim to /chat/completions.

Model ids containing provider/model-name identify Overshoot-hosted paths. Ids without a slash can identify proprietary passthrough models. Capability and response behavior vary. Discover availability at runtime and test image, video, response format, and tool behavior on the selected model. A ready status indicates serving availability, not that every optional request field is supported.

Create and publish a Stream

POST /v1beta/streams with an empty body. The response contains id, active state, publish.type, publish.url, publish.token, expires_at_ms, and ttl_seconds. ttl_seconds is 300. Connect a LiveKit SDK to the wss URL using the short-lived token and publish a video track from a browser, native application, or server process.

The API does not directly ingest RTSP, RTMP, ONVIF, or USB. A separate publisher must produce the LiveKit WebRTC track. Wait for frames before inference. GET /streams/{stream_id} reports state, Stream time, recent frame information, retained counts, lease timing, and ended information. Use those fields to distinguish active video from a connected session with no current frames.

Create a Stream

curl -X POST https://api.overshoot.ai/v1beta/streams \
  -H "Authorization: Bearer $OVERSHOOT_API_KEY"

Renew and delete the Stream

POST /v1beta/streams/{stream_id}/keepalive before the lease expires. A cadence around 90 to 120 seconds leaves recovery time. The response renews expires_at_ms and returns fresh publish information. Feed the new token to the LiveKit room when supported. Keepalive on an ended Stream returns 404.

DELETE /v1beta/streams/{stream_id} when the session finishes. Active moves to ended, and ended is terminal. A deleted or expired id cannot accept new media or inference references. Cleanup should stop capture, disconnect LiveKit, halt keepalive, cancel pending completions, and tolerate repeat deletion attempts in application shutdown logic.

Reference Stream media

Put ovs://streams/{stream_id}?frame_index=-1 inside an image_url content part to select the latest frame. Other image anchors include frame_index, timestamp_ms, and offset_ms. A negative offset selects time before the live edge. Exact anchors support repeatable requests while that frame remains inside the 600-second history.

For video_url, use start_frame_index, start_timestamp_ms, or start_offset_ms with optional matching end anchors and max_fps. max_fps defaults to 1.0. Keep the interval short and relevant. The ovs:// value is a server-side reference, not a fetchable URL. Non-ovs media may use HTTPS URLs or data URLs.

Create a streaming chat completion

POST /v1beta/chat/completions with model, messages, and multimodal content. Set stream to true for SSE and max_completion_tokens for an output cap. A stable thread_id can identify related requests for supported prompt-cache behavior. response_format and tools are accepted where the selected model or provider supports them.

Each SSE event uses a data line containing a chat-completion chunk, and the stream ends with data: [DONE]. Parse deltas incrementally and retain incomplete network chunks between reads. Do not accept partial JSON after interruption. For a non-streaming request, parse the complete OpenAI-shaped response after checking the HTTP status.

Latest-frame completion body

{
  "model": "google/gemma-4-26B-A4B-it",
  "stream": true,
  "max_completion_tokens": 80,
  "messages": [{
    "role": "user",
    "content": [
      { "type": "text", "text": "Describe the visible scene in one sentence." },
      { "type": "image_url", "image_url": { "url": "ovs://streams/{stream_id}?frame_index=-1" } }
    ]
  }]
}

Handle regions, limits, and errors

The documented regions are us-west1 and us-central1. A single request cannot mix Stream references from different regions. Read current limit documentation for request and plan constraints instead of relying on copied values. Billing uses root paths such as /billing/pricing and is separate from the /v1beta base.

Treat 401 as missing or invalid authentication and 403 as a valid identity without access to the resource. Handle 404 for missing or ended Stream operations, 402 for credit state where returned, 429 for limits, and 5xx as service or upstream failures according to the current error reference. Bound retries, preserve error codes, and never convert a failed request into a visual answer.

References

• Full API introduction
• Create a Stream
• Chat completions