Hosts & metering
Decart and Reactor hand your browser a host credential and then run the session on their own, so a plain “booked → ended” clock cannot tell a stream that ran from one that failed to connect, or stop one you walked away from. For these two hosts VideoRouter therefore follows the host’s own record of the session. The video still goes straight between you and the host.
connect object changed and its SDK now needs realtimeBaseUrl; Reactor sessions should be reported to us once connected. In return you are billed the seconds the host actually ran, and ending a session now stops it on the host. What changed, and how to update: Migrating.
Hosts
Several hosts & automatic fallback
Some models are served by more than one host: decart/lucy-2.6 and fal/lucy-2.6-webrtc are the same Decart model at the same price, on Decart directly and on fal. Each host is its own model id because the integration differs: <creator>/<model>/<host> pins a host (decart/lucy-2.6/fal), and fal/lucy-2.6 is accepted as the same thing. To move a caller from one to the other, change the model id — nothing else, as long as you use our JavaScript SDK’s LucyModel.
With the SDK the host really is just the model id. LucyModel reads connect.protocol from the session it was given and streams the right way (Decart’s own SDK for a Decart row, plain WebRTC over our signaling socket for a fal row). It also asks for fallback by default, so if the host you named is out of capacity the other one serves the session and the same code keeps working.
const m = new LucyModel({ model: "decart/lucy-2.6" }); // or "fal/lucy-2.6-webrtc": the only line that changes
await m.connect(token);
await m.start(cameraStream, { prompt: "Anime style", onRemoteStream: show });
m.setPrompt("Red leather jacket");
console.log(m.activeModel); // the host that actually served it
await m.end();
Calling the API directly
Decart’s own SDK joins a LiveKit room; fal’s endpoint is plain WebRTC. Code written against one cannot stream from the other, so on the raw API a fallback that would change the shape of connect is opt-in:
"model": "decart/lucy-2.6"Only hosts whose connect has the same shape are tried (none, for Lucy): you get the error. Safe for code hard-wired to one host."allow_fallbacks": trueThe model’s other hosts are tried too, including ones with a different connect. Read model and connect.protocol in the response."models": ["a", "b"]Exactly these, in this order (1–5), including a dearer host."allow_fallbacks": falseNever fall back, on any host.The response is the host that served the session, with the host-specific connect:
POST /v1/live-video/sessions
{ "model": "decart/lucy-2.6", "allow_fallbacks": true, "max_duration_seconds": 120 }
// Decart had no capacity, so the same call was answered by fal:
{ "id": "lvs_…", "model": "fal/lucy-2.6-webrtc", "status": "ready",
"connect": { "protocol": "webrtc-signaling", "url": "wss://…/v1/live-video/fal/lucy?token=…" },
"fallbacks": [ { "model": "decart/lucy-2.6", "reason": "host_capacity", "message": "…" } ] }
- When it falls back. Only on the host’s side of things:
5xx,429 host_capacity,host_unavailable,pricing_unavailable. Nothing is held or billed for a host that failed to open. - When it never does. Your own errors (a bad request,
402, rate limits) are returned as they are, never retried elsewhere. - Never to a dearer host by default. Lucy is the same price on both.
fastis never downgraded. fal has no fast tier, so aspeed: "fast"request skips fal rather than quietly serving standard.- A host that is down is invisible at creation. Opening a session only mints a token; the host is first touched when your client streams. So the server-side fallback above covers a full or out-of-funds host, not an outage.
LucyModelcovers the rest on the client: if the stream does not connect withinconnectTimeout(25 s) it ends that session (a session that never produced a frame costs nothing) and retries on the host named in the session’salternative_models. On the raw API, readalternative_modelsand do the same. - A live session is not moved. If it drops, open a new one — with
LucyModel, callstart()again.
Decart Lucy: signaling through VideoRouter
connect for the Lucy models is { api_key, base_url, model, max_session_duration_seconds }. api_key is a token for this session only — it is not a Decart credential — and base_url is VideoRouter’s signaling URL (wss://videorouter.sh/api/v1/live-video/decart). Give both to Decart’s realtime SDK; it opens its control socket with us, and we hold the real one to Decart. Camera and result video flow directly between you and Decart as before.
// JavaScript (@decartai/sdk)
const client = createDecartClient({ apiKey: connect.api_key, realtimeBaseUrl: connect.base_url });
# Python (decart)
client = DecartClient(api_key=connect["api_key"], realtime_base_url=connect["base_url"])
- You pay the seconds Decart reports. Decart sends its own meter on that socket (generation started, a tick every 5 s, generation ended). We bill those seconds, rounded up to a whole second and never past your cap. A session that never started generating — including one Decart refused — costs $0.
- Ending it stops it.
POST .../end, reaching the cap, or a lost client closes our side of the socket, and Decart stops generating within about a second. Closing your stream does the same. - The booked tier is the billed tier.
options.speedis fixed when you book; astandardsession cannot be run asfast, and the model cannot be swapped. - Connect within about 40 s of booking. A session nobody connects to is released at $0. There is no heartbeat to send while the stream is connected.
- One stream per session, no reconnect. If the socket drops, the session has ended; book a new one. A second connection to the same session is refused.
- Close codes on the signaling socket:
4401missing or invalidapi_key,4404no such session,4409the session has ended or already has a stream attached,4410the session reached its maximum duration,4502we could not reach Decart. Decart’s own messages (prompt acknowledgements, errors) pass through unchanged, except that a problem on our Decart account is reported to you only as “this model is temporarily unavailable”. - Booking is refused with
502 host_unavailable(nothing held, nothing billed) when we cannot currently start Lucy sessions.
Lucy on a second host: plain WebRTC signaling
fal/lucy-2.6-webrtc and fal/lucy-2.5-webrtc are the same Decart models at the same rate, served by a second host (fal/lucy-vton-2.1-webrtc is the previous-generation try-on model; its first connection can take about 30 seconds while the app starts, and it announces ICE servers as iceservers instead of ready). Use them when you want a vendor-neutral integration (no Decart SDK) or a second path for the same model. The integration is different, so they are their own model ids rather than a silent fallback behind decart/lucy-*: connect is { url, protocol, model, max_session_duration_seconds }, and url is a WebSocket for this session only (a session token, never a host credential). You do the WebRTC offer/answer over it with JSON text frames; the video itself goes straight between your browser and the host.
const ws = new WebSocket(connect.url);
const pc = new RTCPeerConnection({ iceServers: [{ urls: "stun:stun.l.google.com:19302" }] });
const cam = await navigator.mediaDevices.getUserMedia({ video: { width: 1280, height: 704, frameRate: 25 } });
cam.getTracks().forEach((t) => pc.addTrack(t, cam));
pc.ontrack = (e) => { outputVideo.srcObject = e.streams[0]; };
pc.onicecandidate = (e) => e.candidate && ws.send(JSON.stringify({ type: "icecandidate", candidate: {
candidate: e.candidate.candidate, sdpMid: e.candidate.sdpMid, sdpMLineIndex: e.candidate.sdpMLineIndex } }));
ws.onopen = () => ws.send(JSON.stringify({ prompt: "Anime style" })); // first frame = the input; {} is valid
ws.onmessage = async ({ data }) => {
const m = JSON.parse(data);
if (m.type === "ready") {
await pc.setLocalDescription(await pc.createOffer());
ws.send(JSON.stringify({ type: "offer", sdp: pc.localDescription.sdp }));
} else if (m.type === "answer") await pc.setRemoteDescription({ type: "answer", sdp: m.sdp });
else if (m.type === "icecandidate" && m.candidate) await pc.addIceCandidate(m.candidate);
else if (m.type === "error") console.error(m.error);
};
ws.send(JSON.stringify({ prompt: "Red leather jacket" })); // change what it renders while live
- Input frame. Any JSON object with
prompt,reference_image_url(adata:URI, at least 512×512, for character swap or virtual try-on) andenable_prompt_expansion; all optional. Send one first, then again whenever you want to change the edit. - You pay the seconds the host reports. The host counts every 2 s once the answer is applied; we bill those seconds plus at most one more interval, rounded up and never past your cap. A session that never negotiated costs $0.
- Ending it stops it.
ws.close(),POST .../end, reaching the cap, or a lost client closes our side of the host socket, which stops generation and billing at once. The open socket is the heartbeat. One stream per session, no reconnect. - Close codes as for the Decart signaling socket:
4401bad token,4404no such session,4409ended or already attached,4410maximum duration reached,4502we could not reach the host.
Reactor: tell us your session
Your browser creates the Reactor session itself with connect.jwt. Reactor keeps a session running — and billing — after its client disappears, so we end it for you from our side. To know which session is yours, report it once connected:
// browser
import { Reactor } from "@reactor-team/js-sdk";
const reactor = new Reactor({ modelName: connect.model, jwt: connect.jwt });
await reactor.connect(); // connect within connect.connect_within_seconds (60 s) of booking
// tell VideoRouter which Reactor session this is (from your server, or from the browser with a live-video token)
await fetch(`https://videorouter.sh/api/v1/live-video/sessions/${session.id}/host-session`, {
method: "POST",
headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
body: JSON.stringify({ session_id: reactor.getSessionId() }),
});
// ... when you are done
await reactor.disconnect(); // ends the Reactor session; then POST .../end to settle
The Python and JavaScript SDKs wrap the report call: session.report_host_session(reactor.session_id) / await session.reportHostSession(reactor.getSessionId()).
- You pay Reactor’s own record of how long the session ran (from its creation to its close, so a second or two of start-up is included), at most your cap. A booking whose browser never connected is $0.
- Ending it stops it.
POST .../end, the cap, or silence ends that Reactor session from our servers even if your browser is gone or still connected. - Report the session id. It is how we match your session to this booking. If you do not, we pick the one session of that model created since you booked. If you run several sessions of one model at the same time and do not report them, we cannot tell them apart: none is ended early, and each is billed its full booked duration. Reporting removes the ambiguity.
- Keep sending the heartbeat. There is no signaling channel for us to watch, so
POST .../heartbeatabout every 5 s is the only sign that your session is alive; if it stops, we end the session after the silence window (about 40 s) and bill what Reactor ran. The SDKs do this for you. - Connect within 60 s of booking (
connect.connect_within_seconds). The token is short-lived on purpose, and a browser that connects after you have ended the booking is disconnected. - Booking is refused with
502 host_unavailable(nothing held, nothing billed) when we cannot currently start Reactor sessions.
POST /v1/live-video/sessions/{id}/host-session answers 400 invalid_host_session when the id is not a session of this booking (wrong model, created before you booked, unknown, or already used by another booking), and 409 host_session_already_set if a different session is already attached. See the API reference.
Migrating (changed 2026-11-14)
connect.api_key was a Decart client token, base_url was Decart’s API, plus token and expires_at. Billed from booking to /end.api_key is a session token and base_url is VideoRouter’s signaling URL; token and expires_at are gone. Pass realtimeBaseUrl: connect.base_url (JS) or realtime_base_url (Python) to Decart’s SDK. Billed on Decart’s own seconds. No reconnect./end; a session could keep running after you ended it.Token valid 60 s. Report your session with host-session. Ending a booking ends the Reactor session; billed on Reactor’s record.waiting session cost nothing, even though the world was built.A world build you started still owes its world fee; a build that fails is free. Reusing a world_id pays no fee.