Discord

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.

Changed 2026-11-14 — Decart Lucy and Reactor. Decart’s 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:

RequestWhat happens if the named host cannot open the session
"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.
  • fast is never downgraded. fal has no fast tier, so a speed: "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. LucyModel covers the rest on the client: if the stream does not connect within connectTimeout (25 s) it ends that session (a session that never produced a frame costs nothing) and retries on the host named in the session’s alternative_models. On the raw API, read alternative_models and do the same.
  • A live session is not moved. If it drops, open a new one — with LucyModel, call start() 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.speed is fixed when you book; a standard session cannot be run as fast, 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: 4401 missing or invalid api_key, 4404 no such session, 4409 the session has ended or already has a stream attached, 4410 the session reached its maximum duration, 4502 we 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 (a data: URI, at least 512×512, for character swap or virtual try-on) and enable_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: 4401 bad token, 4404 no such session, 4409 ended or already attached, 4410 maximum duration reached, 4502 we 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 .../heartbeat about 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)

ModelBeforeNow
Decart Lucyconnect.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.
Reactor modelsToken valid 5 minutes. Billed from booking to /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.
Happy OysterEnding a 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.