Realtime Videos

Quickstart

Create a realtime session, connect to its video stream, and change the prompt while it is running.

Before you start

  1. A TokenFactory API key (tf_…) from your dashboard. See Authentication.
  2. A model name that has capacity. For a first test use mock-stream, a CPU test model with the same command contract as the real models. See the model catalog.
shell
export TF_BASE_URL=...   # the realtime API host you were given
export TF_API_KEY=tf_...

1. Create a session

curl -sS -X POST "$TF_BASE_URL/v1/realtime/sessions" \
  -H "Authorization: Bearer $TF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "mock-stream", "starting_input": {"state": {"prompt": "a calm lake at sunrise"}}}'

The response is 201 with the session:

response
{
  "id": "rts_86492c38f28b4472b31d4ac9551cb281",
  "status": "ready",
  "model": "mock-stream",
  "started_at": "2026-10-17T20:45:57.019Z",
  "ended_at": null,
  "end_reason": null,
  "usage": { "seconds": 0 }
}

If no GPU slot is free the status is queued and the response includes queue_position(and eta_s once there is enough history to estimate one).

2. Wait until it is ready

Poll GET /v1/realtime/sessions/{id} until status is ready. Every second or two is plenty. Stop and report if it becomes failed or ended.

curl -sS "$TF_BASE_URL/v1/realtime/sessions/$SESSION_ID" -H "Authorization: Bearer $TF_API_KEY"

3. Connect and watch

Video is delivered over WebRTC. There is no published browser SDK yet; the reference client is a headless Python viewer in this repository, realtime-video-infra/tools/viewer.py. It creates the session, negotiates WebRTC through our signaling proxy, receives the video track, optionally changes the prompt, and prints a report of what actually arrived. Install the packages in realtime-video-infra/pods/mock/requirements.txt, then run:

shell
python realtime-video-infra/tools/viewer.py \
  --broker "$TF_BASE_URL" --key "$TF_API_KEY" --model mock-stream \
  --prompt "a calm lake at sunrise" \
  --seconds 10 --switch-after 4 --switch-prompt "neon city at night"

The report includes time to first frame, frame rate, stalls, and whether the prompt change is visible in the pixels:

viewer report (abridged)
{
  "frames": 127,
  "time_to_first_frame_s": 0.061,
  "fps": 15.86,
  "stalls_over_250ms": 0,
  "prompt_switch": { "color_shift": 118.3 }
}

To write your own client, see Connecting media.

4. End the session

curl -sS -X DELETE "$TF_BASE_URL/v1/realtime/sessions/$SESSION_ID" -H "Authorization: Bearer $TF_API_KEY"

DELETEis idempotent and returns final usage. A session also ends on its own at its duration cap, or if the client goes away and the pod's grace period runs out.

← OverviewAuthentication →