Discord
此页面暂无中文版本 — 以下显示英文内容。 查看英文版

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).

Published. Both SDKs are on PyPI and npm as 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.started

Builders 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.update
clock_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) raises LiveVideoError with code == "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

ConstructorNotes
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().
MethodReturns / behavior
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

MemberDescription
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

TypeFields
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, raw
Tokentoken, expires_at, models, max_sessions, max_session_duration_seconds
StatusWAITING, READY, ENDED — strings

Testing 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.