Realtime Videos · API reference

Realtime sessions

Create, inspect, and end realtime sessions, and reach a session's schema and WebRTC signaling.

All requests need Authorization: Bearer tf_…; see Authentication. Bodies are JSON. Errors use { "error": { "message": "…" } }.

Create a session

POST /v1/realtime/sessions

Field	Type	Description
`model`	string, required	A model name from the catalog.
`starting_input`	object	State and commands applied before the first frame. Shape: `{ state?: {…}, commands?: [{ command, data }] }`. See Commands.
`max_duration_s`	integer ≥ 1	Cap on session length. Clamped to the server maximum (600 s by default) and to the model’s own limit.

Returns 201 with a session object. If a slot is free the session is already ready; otherwise queued.

The session object

session

{
  "id": "rts_86492c38f28b4472b31d4ac9551cb281",
  "status": "queued",
  "model": "mock-stream",
  "started_at": null,
  "ended_at": null,
  "end_reason": null,
  "usage": { "seconds": 0 },
  "queue_position": 2,
  "eta_s": 45
}

Field	Description
`id`	Session id, prefixed `rts_`.
`status`	`queued` · `starting` · `ready` · `streaming` · `ended` · `failed`. See Sessions.
`started_at`	ISO-8601 time the pod accepted the session; null while queued. Billing starts here.
`ended_at`	ISO-8601 time it ended; null while live.
`end_reason`	`client` · `timeout` · `pod_error` · `capacity` · `admin`; null while live.
`usage.seconds`	Billed seconds so far (rounded up), final once ended.
`queue_position`	Only while `queued`. 1 is next.
`eta_s`	Only while `queued`, and only once there is enough recent history to estimate. A rough heuristic, not a guarantee.

Get a session

GET /v1/realtime/sessions/{id}

Returns the session object. A session that does not exist, or that belongs to another key, is 404.

End a session

DELETE /v1/realtime/sessions/{id}

Ends the session, frees its GPU slot, stops billing, and returns the final session object with end_reason: "client". Idempotent: ending an already-ended session returns it unchanged. Billing stops when we record the end, even if the pod is slow to confirm.

Get the command schema

GET /v1/realtime/sessions/{id}/schema

Returns the model's OpenAPI 3.1 schema, proxied from the pod. 409 until the session is ready or streaming.

WebRTC signaling

ANY /v1/realtime/sessions/{id}/transport/webrtc/*

Authenticated pass-through to the pod's signaling endpoints. The sequence is described in Connecting media. Same 409 rule before the session is ready. Request bodies are limited to 1 MB.

Errors

Status	When
`400`	Body is not a JSON object; `model` missing; `max_duration_s` not a positive integer; `starting_input` not an object.
`401`	Missing, malformed, or revoked API key.
`404`	Unknown session, a session owned by another key, or `no realtime pods serve model '…'`.
`405`	Method not allowed for that path.
`409`	Media endpoints (schema, signaling) called before the session is ready or streaming.
`413`	Request body over 1 MB.
`502`	The GPU pod returned an error or was unreachable while proxying.

← Connecting media Model catalog →