Overshoot documentation for live VLM applications
Overshoot documentation defines how to publish live WebRTC video and query it with cloud-hosted vision-language models. The current application API uses /v1beta. Start with the quickstart for a complete working path, then use the Stream, media-reference, chat-completions, model, region, limit, and error pages as the production contract. The docs separate live transport from inference: LiveKit carries a published video track, while HTTPS requests select visual context and return OpenAI-compatible completions, including incremental SSE output.
- API version
- /v1betaBase path for Streams, models, and chat completions.
- Stream operations
- 4Create, inspect, keep alive, and delete.
- Lease
- 300 secondsA keepalive renews the lease and supplies a fresh LiveKit token.
- History
- 600 secondsRolling frame history exposed through ovs:// references.
- Streaming
- SSESet stream to true for incremental chat-completion output.
Follow the documentation in build order
Begin with authentication and model discovery. Create a Stream, connect to its returned LiveKit room, and publish one track. Confirm frames through Stream status. Send a latest-frame chat completion. Add keepalive and token refresh. Finally, delete the Stream and release the publisher. This sequence exposes the complete lifecycle before more complex prompts or interfaces hide integration problems.
The quickstart is the shortest path through those steps. The Stream guide explains the leased entity and retained history. LiveKit client flow covers publishing. Chat-completions and Stream media URLs define request content. Keep these pages open while implementing because each owns a different part of the contract.
Use the Stream references as the source of truth
A Stream lasts 300 seconds without keepalive and retains a rolling 600 seconds of frames while active. Keepalive returns a fresh publish token. State moves from active to ended and never returns. GET status fields expose current frame history and lease state. DELETE ends the Stream explicitly.
Read the media URL guide before constructing ovs:// identifiers. Image anchors and video anchors use different query keys. frame_index=-1 means latest. Negative offsets are relative to the live edge. Video segments default to max_fps 1.0. The ovs:// scheme is parsed by the API and cannot be fetched as a public URL.
Use model and completion references together
GET /v1beta/models reports current ids and ready or unavailable status. The model guide describes current choices, while the endpoint keeps the application catalog fresh. Pass the chosen id verbatim. Test media and optional features against that model because providers can differ in video, tools, or structured-output support.
The chat-completions page defines messages, multimodal content parts, output caps, streaming, thread_id, and response fields. Use the error reference alongside it. A syntactically accepted optional field may still depend on provider capability. Production code should surface a clear model or provider error and preserve enough request metadata for diagnosis.
Read region and limit pages before production
Overshoot documents us-west1 and us-central1. Select the region deliberately and store it with each Stream. One chat request cannot combine Stream references from multiple regions. Measure the source and user network path. The product response for hosted models is 200ms, while complete client latency contains additional transport and application work.
Limits can change by product and plan. Read the current limits page and confirm commercial requirements directly. Do not infer throughput, uptime, SLA, or free-tier behavior from examples. Build handling for rate limits, body limits, unavailable models, and ended Streams. A production design should remain understandable when a request cannot run.
Treat examples as patterns and OpenAPI as fields
Examples show the intended sequence and common request shape. The canonical API reference defines required fields, enums, error bodies, and response properties. Keep /v1beta in new code. Billing endpoints are rooted separately. Avoid older version examples from unrelated clients or cached pages when they conflict with the current contract.
Copy an example into a small integration test, then add assertions for state and cleanup. Check create response fields, successful publish, frame arrival, streamed completion termination, keepalive token refresh, and deletion. These tests catch contract drift earlier than a large user-interface test and provide a runnable reference for new engineers.
Build a production reading checklist
Read authentication, regions, limits, errors, lifecycle, best practices, and model availability before launch. Review SSE parsing and cancellation. Verify that API keys stay in a trusted environment. Document the source path because direct RTSP, RTMP, ONVIF, and USB ingest are not part of the public API. Define evidence retention beyond the 600-second window.
Add runbooks for publisher interruption, stale frames, keepalive failure, ended Streams, unavailable models, malformed model output, and partial SSE. Revisit the docs when upgrading dependencies or changing models. Documentation gives the API boundary; your runbooks and tests turn that boundary into a maintainable application.
References
Build from the current documentation
Complete one full Stream lifecycle, then test error and recovery behavior before connecting a production source.