Developer docs

Live video SDKs

The Python and JavaScript SDKs wrap the live-video API: open a session, keep it alive, settle it. They are small on purpose — typed errors, events, a background heartbeat and safe retries — and they follow the shape you would expect from a realtime client (status, sessionId, on / off / once, getLastError()).

What the SDK is — and isn’t

VideoRouter is the session broker. The SDK talks to it: it checks your credits, mints the host’s short-lived credentials, meters the session and settles it. It never carries video. session.connect is the host’s credential, and your browser connects to the host directly with the host’s own SDK — Happy Oyster, Odyssey, Decart. That is why there is no sendCommand or track API here: each host has its own control vocabulary, and we do not wrap it.

How it fits together

1. Your server holds your API key and mints a short-lived token for the browser (create_token / createToken). The token can only drive live-video sessions — it cannot call any billable endpoint and cannot mint more tokens.
2. Your browser uses the JS SDK with that token to open a session. VideoRouter holds a credit reservation and mints the host credentials.
3. The browser hands session.connect to the host’s SDK, which streams video directly from the host.
4. The SDK heartbeats every ~5 s. When the user is done, end() settles the session: you pay for the seconds used and the rest of the hold is released.

Server-to-server is the same minus the token: use the SDK with your key, and pass connect to wherever the host SDK runs.

Quickstart

1. Mint a token on your server

from videorouter_live import LiveVideo

lv = LiveVideo(api_key="llmr_sk_live_...")        # or set VIDEOROUTER_API_KEY

# Your server, per page load / per user. The token is safe to hand to a browser.
token = lv.create_token(
    models=["fal/happy-oyster-adventure"],
    expires_in=300,                                # seconds
    max_sessions=1,
    max_session_duration_seconds=60,
)
return {"token": token.token}                      # e.g. from your /api/live-token route

import { LiveVideo } from "videorouter-live";

const lv = new LiveVideo({ apiKey: process.env.VIDEOROUTER_API_KEY });

// Your server, per page load / per user. The token is safe to hand to a browser.
const { token } = await lv.createToken({
  models: ["fal/happy-oyster-adventure"],
  expiresIn: 300,                                  // seconds
  maxSessions: 1,
  maxSessionDurationSeconds: 60,
});
res.json({ token });                               // e.g. from your /api/live-token route

2. Open and drive a session in the browser

import { LiveVideo } from "videorouter-live";

// tokenProvider is called for the first request and once more if the token has expired (401).
const lv = new LiveVideo({
  tokenProvider: async () => (await fetch("/api/live-token", { method: "POST" }).then((r) => r.json())).token,
});

const session = await lv.createSession({
  model: "fal/happy-oyster-adventure",
  maxDurationSeconds: 60,
  options: { world: { prompt: "a rainy cyberpunk city", perspective: "first_person" } },
});
session.on("statusChanged", (status) => console.log(status));   // waiting -> ready -> ended

await session.waitUntilReady();      // a world takes ~30-120 s to build; nothing is metered while "waiting"
session.startHeartbeat();            // every ~5 s in the background

startHostStream(session.connect);    // hand the host credentials to the host's own SDK (below)

// ... when the user is done:
await session.end();
console.log(session.billedSeconds, session.costUsd, session.endReason);

3. Hand connect to the host’s SDK

connect is host-specific. Its shape per model family:

import { HappyOysterEngine } from "@happy-oyster/js-sdk";

function startHostStream(connect) {
  const engine = new HappyOysterEngine({ APIHost: connect.api_base_url, model: "happyoyster-1.0-adventure" });
  engine.updateToken(connect.token);
  const travel = engine.createTravel({ ticket: connect.ticket, videoElement: document.getElementById("player") });
  return travel.start();
}

import { Odyssey, credentialsFromDict } from "@odysseyml/odyssey";

async function startHostStream(connect) {
  const client = new Odyssey();                                  // no API key in the browser
  await client.connectWithCredentials(credentialsFromDict(connect));
  await client.startStream({ prompt: "A cat walking through a neon city" });
  return client;
}

import { createDecartClient, models } from "@decartai/sdk";

async function startHostStream(connect) {
  // connect.api_key is a short-lived Decart client token, locked to the model you booked.
  const client = createDecartClient({ apiKeyProvider: async () => connect.api_key });
  const camera = await navigator.mediaDevices.getUserMedia({ video: true });
  return client.realtime.connect(camera, {
    model: models.realtime(connect.model),                       // e.g. "lucy-2.5"
    onRemoteStream: (stream) => { document.getElementById("player").srcObject = stream; },
    initialState: { prompt: { text: "Turn me into a watercolor painting", enhance: true } },
  });
}

// Open with options: { session_params: { avatar: { persona, image_uri }, call_mode: "video" } }
// (editing: { image_url, editing_type }). connect then looks like:
//   { protocol: "vidu-s", live_id, call_mode, ws_url, client_secret,
//     rtc: { app_id, channel_id, user_id, token, token_expire_at, provider },
//     render_uid /* editing only: subscribe to this user for the edited picture */ }
// The browser opens `${connect.ws_url}&conn_id=<random>` (control only), sends conn_init, and joins
// Alibaba Cloud RTC with connect.rtc. Or let videorouter-live's ViduAvatarModel / ViduEditingModel do it.

The host snippets use each host’s documented SDK calls; run them against your own session before shipping, since the host SDKs evolve independently of ours.

Session lifecycle

• connect is returned once. It is a short-lived credential and is deliberately not stored or re-served. The SDK keeps it on the session object for you; a session re-fetched with getSession has none — end it and open a new one if you lose it.
• Heartbeat. Call it every ~5 s (the SDK’s startHeartbeat / start_heartbeat does). Without it, the server settles the session itself after a short silence window — a closed tab costs at most that window, never the whole cap.
• Hard cap. Every session ends at max_duration_seconds (default and ceiling are per model; a token can lower the ceiling).
• End always. end() is safe to call twice, and the withSession / session() helpers call it in a finally block.
• Ending while waiting costs nothing; a session that never became ready is settled at $0.

Events

Registering any other event name raises immediately, so a typo can’t silently never fire. Handlers may be async; an exception inside one never breaks the SDK.

Errors

Every failed call throws a LiveVideoError subclass carrying status, code, type and, when the server sent one, retry_after / retryAfter (seconds). Match on the class, not on message text.

Retries & timeouts

• Reads, heartbeats and end retry (default 2 times, exponential backoff) on network errors and 502/503/504.
• Creating a session or a token is never retried. A retried create could open a second billed session. If a create fails with a network error, call models() / check your dashboard before trying again.
• 429s are surfaced, not retried: a ConcurrencyLimitError needs a session to end, and HostCapacityError is yours to back off on (retryAfter).
• Request timeout: 30 s by default (timeout option).

Running in a browser

• Never ship your API key. Use createToken on your server and give the browser the token only. The SDK refuses to start without a key, token or tokenProvider.
• CORS is enabled on /v1/live-video/* (and the /api/v1 alias) for any origin, because auth is a bearer token with no cookies. Other VideoRouter endpoints keep the browser’s same-origin default.
• A token’s lifetime is 1–21,600 s (default 1 h). It only gates new requests; keep minting short ones and use tokenProvider to refresh.
• Bound the blast radius: pass models, max_sessions and max_session_duration_seconds when you mint.