Discord

API reference

All endpoints need an API key with the live_video scope. Example values are placeholders; the price_per_second_usd you see is the model’s real price.

POST/v1/live-video/tokens

Mint a short-lived credential for a browser. Call it from your server with your own key and hand the result to the client: it can only call /v1/live-video session endpoints (never billable endpoints, never this one), so a leaked token is bounded by its lifetime and limits. Sessions opened with it are billed to your organization.

Parameters

ParameterTypeDescription
modelsstring[]Optional. Restrict the token to these live-video model ids (1–20).
expires_inintegerOptional. Lifetime in seconds, 1–21,600 (default 3,600). Out-of-range values are rejected, never silently clamped.
max_sessionsintegerOptional. Sessions this token may hold open at once (1–20) → 429 token_session_limit.
max_session_duration_secondsintegerOptional. Ceiling on a session’s max_duration_seconds (1–3,600) → 400 token_max_duration_exceeded.

Example response

{
  "object": "live_video.token",
  "token": "llmr_sk_live_...",
  "expires_at": "2026-10-13T13:00:00+00:00",
  "models": ["reactor/happy-oyster-adventure"],
  "max_sessions": 1,
  "max_session_duration_seconds": 60
}

Using the token anywhere outside /v1/live-video returns 403 live_token_forbidden; using a model it wasn’t minted for returns 403 model_not_allowed. The caller’s key needs the live_video scope.

GET/v1/live-video/models

The catalog. Never exposes the host. A row with available: false has no verified price yet and can’t be booked.

Example response

{
  "object": "list",
  "data": [{
    "id": "reactor/happy-oyster-adventure", "object": "live_video.model",
    "kind": "world", "control": "stream", "resolutions": ["720p"],
    "max_session_sec": 900, "available": true,
    "price_per_second_usd": 0.0, "price_per_hour_usd": 0.0
  }]
}

kind is generate/world/avatar/edit; control is stream (your browser steers over the host’s channel) today.

POST/v1/live-video/sessions

Open a session. Holds max_duration_seconds × price_per_second against your credits and mints the host credentials (immediately, or once the world is built).

Parameters

ParameterTypeDescription
modelstringRequired. A slug from GET /v1/live-video/models.
max_duration_secondsintegerOptional. 1 to the model’s max_session_sec; defaults to that cap. Above it → 400 max_duration_exceeds_host_limit.
options.worldobjectBuild a new world first (host-specific fields passed through). Session starts waiting. Exclusive with world_id/session_params.
options.world_idstringReuse an existing world; session is ready at once.
options.session_paramsobjectForwarded verbatim to the host’s session call.

Example response

{
  "id": "lvs_...",
  "object": "live_video.session",
  "model": "reactor/happy-oyster-adventure",
  "kind": "world",
  "control": "stream",
  "status": "ready",
  "price_per_second_usd": 0.0,
  "reserved_usd": 0.0,
  "max_duration_seconds": 60,
  "created_at": "2026-10-13T12:00:00+00:00",
  "ready_at": "2026-10-13T12:00:01+00:00",
  "expires_at": "2026-10-13T12:01:01+00:00",
  "heartbeat_interval_seconds": 5,
  "world_id": null,
  "billed_seconds": null,
  "cost_usd": null,
  "end_reason": null,
  "recording_url": null,
  "connect": { "ticket": "...", "token": "...", "api_base_url": "..." }
}

connect appears only in the response that minted it. A waiting session has no connect, ready_at or expires_at yet.

GET/v1/live-video/sessions/{id}

Status and billing so far. If the session is waiting, this call checks the host and, when the world is built, mints the host session — that one response carries connect. Ownership-checked: another organization’s id returns 404.

Parameters

ParameterTypeDescription
idstring (path)The id from POST /v1/live-video/sessions.

status: waiting → ready → ended. After ending, billed_seconds, cost_usd, end_reason and (where available) recording_url are set.

POST/v1/live-video/sessions/{id}/heartbeat

Keep the host lease alive; call about every heartbeat_interval_seconds. If the session is past its cap it is settled instead (end_reason: max_duration), and if the host reports it gone, host_limit. Returns the session object.

Parameters

ParameterTypeDescription
idstring (path)The session id.

POST/v1/live-video/sessions/{id}/end

Settle the session now: debit the real cost, release the rest of the hold. Safe to repeat — a second call returns the same ended session and never debits twice. Ending a waiting session costs nothing, except the world fee of a world build you already started. For Decart and Reactor, ending also stops the host session.

Parameters

ParameterTypeDescription
idstring (path)The session id.
host_travel_idstring (body)Optional. The host’s own travel/run id. When given we ask the host for its authoritative duration (billed if larger than our clock) and fetch the replay.

end_reason is one of client, max_duration, heartbeat_timeout, host_error, host_limit, or abandoned (a world that never became ready).

POST/v1/live-video/sessions/{id}/host-session

Reactor only. Report the Reactor session your browser created with connect.jwt (the SDK’s getSessionId() / session_id). We verify it against Reactor and attach it to this booking, so ending the booking ends exactly that session and you pay Reactor’s own record of it. Safe to repeat with the same id. Returns the session object. Errors: 400 invalid_host_session, 409 host_session_already_set, 409 session_not_open.

Parameters

ParameterTypeDescription
idstring (path)The session id.
session_idstring (body)Required. The Reactor session id.

WS/v1/live-video/decart/v1/stream

Decart Lucy only. The signaling socket for Decart’s realtime SDK, relayed to Decart; you do not call it yourself — give connect.base_url and connect.api_key to the SDK, which opens <base_url>/v1/stream?api_key=…&model=…. One connection per session; the booked model and speed are used whatever the query string says. Closing it ends the Decart stream. Close codes are listed under Decart Lucy.

Query

ParameterTypeDescription
api_keystring (query)Required. connect.api_key from the session that booked this stream.
resolutionstring (query)Optional, passed to Decart.

Limits & errors

Status / codeWhen
429 concurrency_limitToo many live sessions open for your organization. Retry-After is set; ending a session frees its slot.
429 host_capacityNo capacity on that model right now. Retry shortly — sessions are never queued, a queued real-time session is useless.
402 insufficient_creditsThe hold for this session isn’t covered by your balance.
400 max_duration_exceeds_host_limitmax_duration_seconds is above the model’s host cap.
400 invalid_session_paramsVidu and Boson: options.session_params is missing, has an unsupported key, or a value is invalid (Vidu: an image that is not an http(s) / data:image/ URI; Boson: a missing or malformed transport, a transport.url that is not wss://<project>.livekit.cloud, or an avatar_id that is not a builtin_* preset).
400 host_rejected_requestVidu or Boson refused the request itself — typically a Vidu character or reference image that failed its content review, or a LiveKit room or token Boson could not use.
400 invalid_host_sessionReactor: the id you reported is not a session of this booking — wrong model, created before you booked, unknown, or already used by another booking.
409 host_session_already_setReactor: a different session is already attached to this booking.
409 session_not_openhost-session was called on a session that has already ended.
WS 4401 / 4404 / 4409 / 4410 / 4502Decart signaling socket: invalid token / no such session / session ended or already attached / reached its maximum duration / could not reach Decart. See Decart Lucy.
502 host_unavailableThe model cannot start sessions right now. Nothing was held or billed; retry later.
502 pricing_unavailableNo verified price for that model yet (see Preview note).
404No such session, or it belongs to another organization.
403 missing_scopeThe API key lacks the live_video scope.

Full request and response shapes: endpoints above.