Realtime Videos · Concepts
Sessions
A session is one live generation on one GPU: its model state, its prompt, and its media stream.
What a session is
A session holds a GPU slot for as long as it lives. In the preview each GPU pod runs one session at a time, so a model's total concurrent sessions equals the number of pods serving it. A session is created over HTTPS, streamed over WebRTC, and ended over HTTPS (or by a limit).
Status
| Status | Meaning | Billed |
|---|---|---|
queued | No slot is free. The response carries queue_position and, when we have history, eta_s. | No |
starting | A pod was chosen and is being asked to start the session. Usually brief. | No |
ready | The pod accepted the session. WebRTC signaling and commands are available. No client may be connected yet. | Yes |
streaming | Frames are being generated for a connected client. | Yes |
ended | Finished. See end_reason. | Final |
failed | Could not run or died. See end_reason. | Final |
Media endpoints (/schema and /transport/webrtc/*) return 409 until the session is ready or streaming.
Why a session ended
| end_reason | Cause |
|---|---|
client | You called DELETE. |
timeout | It reached its duration cap, or the pod ended it after the client left and the grace period ran out. |
pod_error | The GPU pod crashed or became unreachable, or two start attempts failed. The session is not recoverable; open a new one. |
capacity | It waited in the queue past the wait limit and was never given a slot. |
admin | An operator ended it. |
Queueing
When every slot is busy the session is created as queued rather than rejected. A background loop promotes queued sessions in order as slots free up. If a session waits longer than the queue limit (120 s by default) it becomes failed with end_reason: "capacity". Treat that as “try again later”, not as an error in your request. Queued time is never billed.
Failure and recovery
- If a pod dies mid-session, the session fails with
pod_errorand billing stops at the last time we confirmed the pod was healthy. - Sessions are not migrated or resumed. Opening a new session restarts the stream; it does not continue it.
- If starting on the chosen pod fails, we retry once on a different pod before failing the session.
Duration caps
Pass max_duration_s when creating a session to cap its length. It is clamped to the server maximum (600 s by default). Individual models can be shorter: longlive-1.3b cannot run past 240 s of video because of its positional-embedding table.