All four are billed per second of session time, drawn from the same workspace credit balance as other Router calls. See Router pricing for rates. A session needs a funded workspace: with no credits, opening one is refused with
402.
The WebSocket path is
/v2/realtime/{provider}/{model}, where {provider} is the broker that serves the model and {model} is the full model id. That is why google appears twice in the Genie 4 path.Authentication
Realtime routes accept the same credentials as other Router calls.-
From a server, send your API key in
X-API-Key: comfyui-...orAuthorization: Bearer comfyui-...on the WebSocket upgrade request or the signalling request. Keep API keys on your server; never ship them to a browser. -
From a browser, a WebSocket cannot set request headers. A browser signed in to a Comfy account passes its Firebase ID token in the subprotocol offer instead, alongside
comfy-realtime.v1:The token must be an unexpired Firebase ID token. API keys are never accepted this way, and credentials are never accepted in the URL query string. An offer that carriescomfy-bearer.withoutcomfy-realtime.v1is refused with400before any session opens. When you offercomfy-realtime.v1, the server selects it in the101response. The subprotocol offer applies to the WebSocket sessions only. WebRTC signalling is ordinary HTTP, so a browser sendsAuthorization: Bearer <Firebase ID token>as a header there.
WebSocket sessions
Open a session with a WebSocket upgrade towss://api.comfy.org/v2/realtime/{provider}/{model}. Router authenticates the upgrade, checks your balance, and relays frames between your client and the model for the life of the session.
Session rules
- One live WebSocket session per workspace. A second upgrade while one is live is refused with
429andcode: router.realtime.session_already_live. Close the first session before opening another. - Metering starts at the
101. Billing runs from the moment the upgrade succeeds until the session ends, in whole seconds, with a minimum of one second. Opening a session and closing it at once still bills that minimum. - Balance is re-checked while the session runs. Router meters the session and re-checks your balance every 15 seconds. If the balance still covers some time, the session’s cap is shortened to match (a Genie 4 session then ends at that cap with
1000). When the balance can no longer cover even one more second, or the account is blocked, Router drops the connection without a close frame (most clients report close code1006). If you ran out of credits, top up before reconnecting. A session’s maximum length is also shortened up front to what your balance covers.
Genie 4
google/genie-4 generates an interactive world from a text prompt that you then move through with key presses. It accepts text frames only, each a JSON object with an event_type. A binary frame, or a message over 64 KiB, ends the session.
The ten keys a
user_action can name:
Any other event type, field or key, a
user_action or input before world_setup, or a sustained flood of events (beyond a burst of about 120, then about 60 per second) ends the session with close code 1008 (policy violation). Nothing in the refused message reaches the model.
The model’s own events come back on the same socket. A session ends:
- after the model’s
interaction.completedevent, with close code1000; - after the model’s
errorevent, with the provider’s close code or1011; - at the 120-second session cap (or sooner, if your balance covers less), with close code
1000.
key_down and one key_up per physical key press and skips auto-repeat, which keeps it well inside the event rate.
Grok Voice
xai/grok-voice/realtime is a speech-to-speech conversation. The session speaks fal’s realtime wire format: send each event as a MessagePack-encoded binary frame; responses arrive as MessagePack binary frames or JSON text frames. The events inside are xAI’s realtime voice events.
You can send these client events: session.update, x-fal-session.configure, input_audio_buffer.append, input_audio_buffer.commit, input_audio_buffer.clear, conversation.item.create, conversation.item.delete, conversation.item.truncate, response.create and response.cancel. Each event may carry only its documented fields.
- Tools are limited to client-executed
functiontools. Server-side tools such as MCP servers and web or X search are refused. - Image and video content is refused anywhere in an event.
- If
session.modelis set, it must begrok-voice-latest,grok-voice-3.0orgrok-voice-2.0.
1008. The session cap is 30 minutes, shortened up front to what your balance covers; at the cap the connection is closed without a close frame.
A Grok Voice session costs **$0.0011869 per second** (about $0.0712 per minute; at 211 credits = $1, about 0.25 credits per second or 15 credits per minute). It bills for the whole time the socket is open, whether or not audio is flowing.
Node
input_audio_buffer.append (base64 audio), then input_audio_buffer.commit and response.create.
WebRTC world models
fal-ai/abot-world-0 and fal-ai/lingbot-world-2 stream video over WebRTC. The media travels directly between the browser and fal, peer to peer; Router handles only the HTTP signalling that sets the connection up, adding fal’s credentials so your client never holds them.
Every signalling call is a POST to https://api.comfy.org/v2/realtime/wma/fal with your Comfy credential, a JSON body, and the real destination in the x-fal-target-url header. This is the proxy contract fal’s JavaScript client uses, so you can point that client’s proxy setting at this route. Only these destinations are accepted; anything else is refused with 400 and code: router.realtime.wma_target_rejected:
The body must be a JSON object of at most 64 KiB with no repeated keys. Spell
app_id and session_id exactly so; a different capitalization is refused with 400.
Session lifecycle and billing
- Maximum length. Each session runs for at most 480 seconds.
- Heartbeats. Send one every 5 seconds, as fal’s client does. Router forwards at most one per second per session; a faster heartbeat is refused with
429andRetry-After: 1. Heartbeats and closes are accepted only for asession_idyour account opened and has not closed; otherwise the answer is404withcode: router.realtime.wma_session_not_found. - Billing. A session is billed per second from when it opens until 5 seconds after its last heartbeat, up to the 480-second maximum. Closing the session settles the bill right away; a session whose heartbeats stop for more than 15 seconds is settled on its own. The close response’s
settled: falsemeans the bill is still being finalized and lands shortly. - Balance check at open. Router cannot stop a peer-to-peer session once it starts, so opening one requires a balance that covers the full 480 seconds of this session plus the full length of every WebRTC session your workspace already has open. If it does not,
/sessionis refused with402andcode: router.realtime.insufficient_credits. This is a check, not a reservation: other spend can draw on the same balance while a session runs. - Concurrent sessions. A workspace can hold 2 WebRTC world-model sessions at a time. A closed session keeps its slot until about 480 seconds after it opened (plus a short settle window), so a quick close-and-reopen can be refused with
429andcode: router.realtime.concurrency_limit; wait for theRetry-Afterthe response names.
Errors
A refused upgrade or signalling call answers with an HTTP status and a JSON body carryingdetail, error_type and a code that names the reason. Branch on code or error_type rather than on detail. Once a WebSocket session is open, problems are reported with a close code instead.
The upgrade and the
/ice and /session signalling calls spend the same per-caller request allowance as other Router calls.
Next
Capabilities and limits
What Router supports, and its deadlines and rate limits.
Router pricing
Rates and billing options.