Live video SDKs
Python SDK
A sync client (LiveVideo) and an asyncio client (AsyncLiveVideo) with the same surface; on the async client every network method is a coroutine. Read the SDK overview first for the concepts (broker model, tokens, connect, heartbeat).
videorouter-live. A live-video model can only be booked once its price is verified (see Live video & world models), and the SDKs surface that as PricingUnavailableError.pip install videorouter-live
Requires Python 3.9+. The only dependency is httpx.
Quickstart (sync)
from videorouter_live import LiveVideo
lv = LiveVideo(api_key="llmr_sk_live_...") # or set VIDEOROUTER_API_KEY
with lv.session(
"reactor/happy-oyster-adventure",
max_duration_seconds=60,
) as s:
# The session is already ready and heartbeating in the background.
send_to_browser(s.connect) # host credentials - returned once by the server
wait_for_user_to_finish()
# Settled on exit, even if your code raised.
print(s.status, s.billed_seconds, s.cost_usd, s.end_reason)
lv.session(...) creates the session, waits until it is ready, starts the heartbeat, and settles it on exit — even if your code raised. While a world is building the session is waiting and nothing is metered.
Async client
import asyncio
from videorouter_live import AsyncLiveVideo
async def main():
async with AsyncLiveVideo(api_key="llmr_sk_live_...") as lv:
async with lv.session("decart/lucy-2.5", max_duration_seconds=120,
options={"speed": "standard"}) as s:
s.on("error", lambda e: print("heartbeat problem:", e))
await hand_to_browser(s.connect)
await asyncio.sleep(30)
print(s.cost_usd)
asyncio.run(main())
Heartbeats run as an asyncio task on the running loop; handlers may be coroutine functions.
Manual lifecycle & events
s = lv.create_session("reactor/happy-oyster-adventure", max_duration_seconds=60)
print(s.status) # "ready" - connect is available now
s.on("status_changed", lambda st: print("->", st))
s.on("ended", lambda sess: print("settled:", sess.cost_usd))
s.wait_until_ready(timeout=180, poll_interval=4) # polls; the poll that sees it ready returns s.connect
s.start_heartbeat() # daemon thread, every ~5 s
use(s.connect)
s.end(host_travel_id="...") # optional (Happy Oyster): bill on the host's own duration and fetch the replay
Use the manual flow when the session outlives one function, or when you want to own the polling. get_session(id) rebuilds a handle from an id (it never carries connect).
Browser tokens
token = lv.create_token(models=["reactor/happy-oyster-adventure"], expires_in=300,
max_sessions=1, max_session_duration_seconds=60)
token.token # "llmr_sk_live_..." - give this to the browser
token.expires_at # ISO timestamp
Pass the token to the JavaScript SDK. A token can only drive live-video sessions (never billable endpoints, never create_token), is capped by the limits you set, and expires in expires_in seconds (1–21,600, default 3,600).
Nuance Live
The Python SDK never carries media, and videorouter_live.nuance keeps that: it opens the broker session with the right options and speaks Nuance's nuance_live data-channel protocol as pure functions — no LiveKit dependency — so you can drive it from the livekit package, a native app or a test.
from videorouter_live import LiveVideo, nuance
lv = LiveVideo()
opts = nuance.session_options(
persona_id="sonia", system_prompt="You are Sonia, a librarian.", timezone="Europe/London", end_user_id="user_42",
delegation={"type": "responses", "responses": {"model": "default", "tools": [FIND_BOOK]}}, runtime_tools={"end_call": True})
with lv.session("nuance/nuance-live", options=opts) as s:
room = s.connect # livekit_url, token, conversation_id, data_topic ("nuance_live"), warnings
reader, tools = nuance.EventReader(), nuance.ToolRoundTrip()
# join room["livekit_url"] with room["token"], publish the microphone; then, for each packet on topic "nuance_live":
for event in reader.feed(packet): # message.part series are joined for you
for call in tools.feed(event): # each call of YOUR tools, as the backend makes it
for out in tools.result(call.call_id, run(call.name, call.arguments)): # sent once the step is complete
send(out)
for out in tools.take_outbox(): # results that were ready before the step completed
send(out)
send(nuance.append("thinking", "The user opened the catalog.", while_speaking="revise")) # only after session.startedBuilders for every client event:
session_options(...)The options for create_session: persona, prompt, expressiveness, timezone, end-user id, green screen, delegation, runtime tools, camera, raw interface setup.append · response_create · typed_words · tool_outputAppends (thinking / instructions / commentary), response.create, typed words, a tool result.interrupt · floor_hold · floor_release · mute_input · unmute_inputStop the reply, floor holds, input mute.update · set_tools · closesession.updateclock_sync_pong(ping)Answer each clock_sync_ping on the clock-sync topic, reliably, at once.encode(event)JSON bytes plus whether the event is over 64,000 bytes and must go as a LiveKit text stream.EventReader · ToolRoundTripDecode incoming packets; run the tool round trip (calls surface as made; results go back together).Decart Lucy and Reactor
These two hosts are metered from the host’s own record of the session, so each needs one extra step on your side. Everything else (opening, heartbeats, settling) is the same as for every model. Details and the reasons: How Decart and Reactor are metered.
Decart Lucy. s.connect is {"api_key", "base_url", "model", "max_session_duration_seconds"}. api_key is a token for this session only (not a Decart credential) and base_url is VideoRouter’s signaling URL. Give both to Decart’s Python SDK, which then opens its control socket with VideoRouter; the video still goes straight to Decart. You pay the seconds Decart reports, and a session that never starts streaming is free. Connect within about 40 s of opening; there is no reconnect (a dropped stream means a new session).
from decart import DecartClient # pip install "decart[realtime]"
from videorouter_live import LiveVideo
lv = LiveVideo()
with lv.session("decart/lucy-2.5", max_duration_seconds=120, options={"speed": "standard"}) as s:
c = s.connect
client = DecartClient(api_key=c["api_key"], realtime_base_url=c["base_url"])
# ... then connect and stream as in Decart's Python SDK docs. Leaving the block ends the session,
# which stops the Decart stream.
Reactor. s.connect is {"jwt", "base_url", "model", "expires_at", "max_session_duration_seconds", "host_session_path", "connect_within_seconds"}. Your client creates the Reactor session itself with the jwt (valid 60 s) and then reports it with report_host_session. VideoRouter then ends exactly that session when you end the booking, and you pay Reactor’s own record of how long it ran; a booking whose client never connected is free.
import asyncio
from reactor_sdk import Reactor # pip install reactor-sdk
from videorouter_live import AsyncLiveVideo
async def main():
async with AsyncLiveVideo() as lv:
async with lv.session("reactor/helios", max_duration_seconds=120) as s: # heartbeats in the background
reactor = Reactor(s.connect["model"], jwt=s.connect["jwt"])
await reactor.connect() # within 60 s of opening
await s.report_host_session(reactor.session_id) # tell VideoRouter which session this is
... # steer it with Reactor's commands
await reactor.disconnect() # leaving the block settles the booking
asyncio.run(main())
report_host_session(host_session_id)raisesLiveVideoErrorwithcode == "invalid_host_session"(status 400) if the id is not a session of this booking, or"host_session_already_set"(409) if another session is attached. Repeating the same id is fine.- Without the report we pick the one session of that model created since you opened. If you hold several sessions of one model at once and do not report them, none can be told from another: none is ended early and each is billed its full duration.
- Keep the background heartbeat on (
auto_heartbeat=True, the default): for Reactor it is the only sign that your session is alive.
Generating videos
The clients also wrap the /v1/videos generation API (AsyncLiveVideo has the same surface as coroutines). Params are the API’s own fields, passed through unchanged — see Video generation. It needs an API key; a browser token is live-video only. Creating a job is never retried, so a flaky network cannot bill you twice.
from videorouter_live import LiveVideo
lv = LiveVideo() # reads VIDEOROUTER_API_KEY
# Create and wait
job = lv.videos.generate({
"model": "heygen-video-1",
"prompt": "A presenter says: 'Welcome to VideoRouter.'",
"duration_secs": 5,
})
print(job.url)
# Or step by step
queued = lv.videos.create({"model": "wan-3.0-prime", "prompt": "A robotic arm in a lab"})
queued.wait(timeout=600, poll_interval=5) # raises VideoGenerationError / TimeoutError
again = lv.videos.get(queued.id)job.status, job.done, job.failed, job.url / job.urls, job.error and job.raw are available on every job.
Handling errors
from videorouter_live import (InsufficientCreditsError, ConcurrencyLimitError, HostCapacityError,
PricingUnavailableError, LiveVideoError)
try:
s = lv.create_session("reactor/happy-oyster-adventure", max_duration_seconds=60)
except InsufficientCreditsError:
... # top up, or book fewer seconds
except ConcurrencyLimitError as e:
... # end a session first; e.retry_after is set
except HostCapacityError as e:
time.sleep(e.retry_after or 5) # the host is full right now - sessions are never queued
except PricingUnavailableError:
... # model.available is False
except LiveVideoError as e:
print(e.status, e.code, e.message)
The full class table is in the overview. All classes subclass LiveVideoError and carry status, code, type, retry_after, body.
Reference
Clients
LiveVideo(api_key=None, *, token=None, base_url=..., timeout=30.0, max_retries=2, http_client=None)api_key is your server key; token is a browser-safe token from create_token. With neither, VIDEOROUTER_API_KEY is read. base_url defaults to https://videorouter.sh/api/v1. http_client lets you inject an httpx.Client (proxies, tests). Use as a context manager or call close().AsyncLiveVideo(...)Same arguments; http_client is an httpx.AsyncClient. async with or await aclose().models()list[Model]. available is False until the model has a verified price.create_token(*, models=None, expires_in=None, max_sessions=None, max_session_duration_seconds=None)Token. Server-side only.create_session(model, *, max_duration_seconds=None, options=None)LiveSession. Never retried.get_session(session_id)LiveSession (no connect).session(model, *, max_duration_seconds=None, options=None, wait_until_ready=True, auto_heartbeat=True, ready_timeout=300, poll_interval=4, heartbeat_interval=None)Context manager (async with on the async client): create → wait → heartbeat → settle on exit.LiveSession / AsyncLiveSession
id · session_idThe session id (lvs_...).modelThe model slug.status · get_status()Status: waiting, ready, ended (a str subclass, so s.status == "ready" works).connectHost credentials, or None (waiting, or a re-fetched session).stream_url · stream_headersComponent-edition models (vidu/vidu-s2-avatar-component) only, else None: the relayed WebSocket for PCM audio and transcripts, and the Authorization header it needs (a key never goes in the URL). Use any WebSocket client, e.g. websockets.connect(s.stream_url + "?conn_id=abc", additional_headers=s.stream_headers); the protocol is on the live-video page.world_id, billed_seconds, cost_usd, end_reason, recording_url, expires_atServer fields; the billing fields are set once ended.rawA copy of the last server response.refresh()Re-read. For a waiting session this advances it; the call that sees the world built returns connect.wait_until_ready(timeout=300, poll_interval=4)Raises TimeoutError or SessionStateError (ended while waiting).heartbeat()One beat. Raises SessionStateError on an ended session.start_heartbeat(interval=None) · stop_heartbeat()Background beat (daemon thread / asyncio task). Default interval: the server’s 5 s. Stops itself on 404 / 401.report_host_session(host_session_id)Reactor: report the Reactor session your client created (reactor.session_id). We then end exactly that session with this one and bill Reactor’s own record of it. Raises SessionStateError on an ended session. See Decart Lucy and Reactor.end(host_travel_id=None)Settle. Idempotent. host_travel_id (Happy Oyster) bills on the host’s own duration and fetches the replay.on(event, fn) · once · offEvents status_changed, ended, heartbeat, error. Unknown names raise ValueError.last_error · get_last_error()The last background-heartbeat error.Types
Modelid, kind (world / edit / ...), control, max_session_sec, available, price_per_second_usd, price_per_hour_usd, resolutions, description, speeds, fast_price_per_second_usd, rawTokentoken, expires_at, models, max_sessions, max_session_duration_secondsStatusWAITING, READY, ENDED — stringsTesting your code
import httpx
from videorouter_live import LiveVideo
def handler(request: httpx.Request) -> httpx.Response:
return httpx.Response(200, json={"object": "list", "data": []})
lv = LiveVideo(api_key="test", base_url="http://test/v1",
http_client=httpx.Client(transport=httpx.MockTransport(handler)))
assert lv.models() == []
The package ships a py.typed marker, so type checkers see the annotations.