Create stream
Open a Stream and get back a stream_id plus a LiveKit room URL and publish token, with a fixed 600-second retained frame history.
What you get
The response carries:id— pass this in every later URL:/v1beta/streams/{id}/...plus stream URLs you embed in chat completion messages.publish.url+publish.token— feed these to a LiveKit client SDK to connect a video source. Any LiveKit publisher works (browser, native, server-to-server). The token is short-lived; use the one returned by/keepaliveif your publisher reconnects later.expires_at_ms+ttl_seconds— the lease deadline. Call/keepalivebefore it elapses (every ~2 minutes is safe). After expiry the stream’sstateflips toendedand stays there.
active state immediately, even before the first frame arrives. GET /streams/{id} returns last_frame_at_ms: null until a publisher actually delivers a frame.
Server-pulled sources
Send asource body to have the server pull the video from an rtsp:// camera or HLS playlist instead of accepting a publisher. publish comes back null, and GET /streams/{id} reports last_pull instead. The source must be reachable from the public internet, and a url that cannot be opened returns 422 after about 15 seconds of retries. See Camera sources.Authorizations
Every public HTTP request requires Authorization: Bearer <api_key>, except
GET /models and the public /billing/pricing endpoints.
401means the key is missing, unknown, or revoked.403means the key is valid but cannot access the requested resource.- The publish token returned by
POST /streamsis only for publishing media to LiveKit. It does not replace the API key for HTTP calls.
Headers
Optional hint to route the request to the region that owns the stream. If the
request reaches the wrong region the API returns 409 with a region_error body.
us-west1, us-central1 Body
Omit the body entirely to publish video yourself with the returned publish
credentials. Supply source to have the server pull the video instead.
A server-pulled video source. The server connects to this url itself and publishes the video into the stream, so no client publisher is involved. The url must resolve to a publicly routable address: private, loopback, and link-local addresses are rejected. The url is never returned in any response, because rtsp urls commonly embed camera credentials.
Response
Stream created.
Unique stream identifier. Use this in every subsequent stream URL.
Always active for a freshly created stream.
active Publish credentials, or null for server-pulled sources, which have no client publisher.
Wall-clock Unix ms when the lease will expire if not renewed via /keepalive.
Lease TTL in seconds. Currently 300 for all streams.
300
How video reaches this stream. The source url itself is never echoed back.