Skip to main content
POST
Create stream

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 /keepalive if your publisher reconnects later.
  • expires_at_ms + ttl_seconds — the lease deadline. Call /keepalive before it elapses (every ~2 minutes is safe). After expiry the stream’s state flips to ended and stays there.
The stream sits in 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 a source 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

Authorization
string
header
required

Every public HTTP request requires Authorization: Bearer <api_key>, except GET /models and the public /billing/pricing endpoints.

  • 401 means the key is missing, unknown, or revoked.
  • 403 means the key is valid but cannot access the requested resource.
  • The publish token returned by POST /streams is only for publishing media to LiveKit. It does not replace the API key for HTTP calls.

Headers

X-Overshoot-Region
enum<string>

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.

Available options:
us-west1,
us-central1

Body

application/json

Omit the body entirely to publish video yourself with the returned publish credentials. Supply source to have the server pull the video instead.

source
object

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.

id
string<uuid>
required

Unique stream identifier. Use this in every subsequent stream URL.

state
enum<string>
required

Always active for a freshly created stream.

Available options:
active
publish
object | null
required

Publish credentials, or null for server-pulled sources, which have no client publisher.

expires_at_ms
integer
required

Wall-clock Unix ms when the lease will expire if not renewed via /keepalive.

ttl_seconds
integer
required

Lease TTL in seconds. Currently 300 for all streams.

Example:

300

source
object

How video reaches this stream. The source url itself is never echoed back.