--- title: "Comfy Router 实时语音会话" sidebarTitle: "实时语音" description: "通过 Comfy Router 打开 Grok Voice 实时 WebSocket 会话:端点、认证、按秒计费、会话限制和关闭代码。" translationSourceHash: 2555a808 translationFrom: development/comfy-router/realtime.mdx translationBlockHashes: "_intro": c24aeb22 "Authentication": 588d5135 "WebSocket sessions": 9f0733ee "WebRTC world models": e3d1be35 "Errors": 507d94b1 "Next": aedde44a --- 大多数 Router 模型接收一次请求,并返回已完成的结果。实时模型则维持一个持续会话:你在模型运行期间发送输入,并在输出产生时实时接收。Router 通过两种接口提供这些模型: | 模型 | 功能 | 接口 | | --- | --- | --- | | `google/genie-4` | Genie 4 交互式世界模型,由按键与文本操控 | WebSocket 会话,`GET /v2/realtime/google/google/genie-4` | | `xai/grok-voice/realtime` | Grok Voice 语音到语音对话 | WebSocket 会话,`GET /v2/realtime/fal/xai/grok-voice/realtime` | | `fal-ai/abot-world-0` | 交互式世界模型,通过 WebRTC 传输视频 | WebRTC 信令,`POST /v2/realtime/wma/fal` | | `fal-ai/lingbot-world-2` | 交互式世界模型,通过 WebRTC 传输视频 | WebRTC 信令,`POST /v2/realtime/wma/fal` | 这四个模型都按**会话时间的每秒**计费,与其他 Router 调用一样从同一工作区积分余额中扣除。费率参见 [Router 定价](/zh/development/comfy-router/pricing)。会话需要工作区有可用余额:没有积分时,打开会话会被拒绝并返回 `402`。 WebSocket 路径为 `/v2/realtime/{provider}/{model}`,其中 `{provider}` 是承载该模型的中间服务,`{model}` 是完整的模型 ID。这就是 Genie 4 的路径中 `google` 会出现两次的原因。 ## 认证 实时路由接受与其他 Router 调用相同的凭据。 - **从服务器发起时**,在 WebSocket 升级请求或信令请求中,通过 `X-API-Key: comfyui-...` 或 `Authorization: Bearer comfyui-...` 发送你的 API 密钥。请将 API 密钥保存在你的服务器上,绝不要将其下发到浏览器。 - **从浏览器发起时**,WebSocket 无法设置请求头。已登录 Comfy 账号的浏览器改为在子协议 offer 中携带其 Firebase ID token,并与 `comfy-realtime.v1` 一同提供: ```js const ws = new WebSocket(url, ["comfy-realtime.v1", "comfy-bearer." + idToken]); ``` 该 token 必须是尚未过期的 Firebase ID token。这种方式绝不接受 API 密钥,也绝不在 URL 查询字符串中接受凭据。若 offer 携带了 `comfy-bearer.` 却没有 `comfy-realtime.v1`,服务器会在任何会话开启之前以 `400` 拒绝它。当你提供 `comfy-realtime.v1` 时,服务器会在 `101` 响应中选择该子协议。 子协议 offer 仅适用于 WebSocket 会话。WebRTC 信令是普通 HTTP,因此浏览器在那里以请求头形式发送 `Authorization: Bearer `。 ## WebSocket 会话 通过 WebSocket 升级到 `wss://api.comfy.org/v2/realtime/{provider}/{model}` 来打开会话。Router 会对升级请求进行身份验证、检查你的余额,并在会话存续期间于客户端与模型之间中继数据帧。 ### 会话规则 - **每个工作区只能有一个活跃的 WebSocket 会话。** 当一个会话处于活跃状态时,第二次升级会被拒绝,返回 `429` 和 `code: router.realtime.session_already_live`。请先关闭第一个会话,再打开另一个。 - **计量从第一个数据帧开始。** 按整秒计费,最短为一秒。对于 `google/genie-4`,计费从模型发出第一个数据帧时开始;如果会话在此之前结束,即在最初的 20 秒内结束,则不产生费用。如果 20 秒后仍未收到任何数据帧,则从升级成功的那一刻开始计费。其他模型从 `101` 开始计费。 - **会话运行期间会重新检查余额。** Router 会对会话进行计量,并每 15 秒重新检查一次你的余额。如果余额仍能覆盖一段时间,会话的上限会被缩短以与之匹配(此时 Genie 4 会话会在该上限处以 `1000` 结束)。当余额连再多一秒都无法覆盖,或账户被封锁时,Router 会在不发送关闭帧的情况下断开连接(大多数客户端会报告关闭代码 `1006`)。如果积分已用完,请在重新连接之前充值。会话的最大时长也会预先缩短为你的余额所能覆盖的时长。 ### Genie 4 `google/genie-4` 会根据文本提示词生成一个交互式世界,随后你可以通过按键在其中移动。它**只接受文本帧**,每一帧都是一个带有 `event_type` 的 JSON 对象。二进制帧或超过 64 KiB 的消息会结束会话。 | `event_type` | 字段 | 说明 | | --- | --- | --- | | `world_setup` | `world_prompt: { "text": "..." }` | 必须是第一个事件。提示词为必填项,不能为空,且最大 8 KiB。仅限文本:`reference_image` 或任何图像或视频字段都会被拒绝。重复发送相同的 `world_setup` 会被忽略;发送提示词不同的 `world_setup` 会结束会话。 | | `user_action` | `action`、`input` | `action` 为 `key_down`、`key_up` 或 `key_click`。`input` 是下面十个按键之一。 | | `input` | `content: [{ "type": "text", "text": "..." }]` | 用文本操控世界。仅支持文本部分,每部分最大 8 KiB。 | | `interaction.complete` | 无 | 正常结束会话。发送时不要带其他字段。 | `user_action` 可以指定的十个按键: | 用途 | 按键 | | --- | --- | | 移动 | `key_w`、`key_s`、`key_a`、`key_d` | | 相机 | `arrow_up`、`arrow_down`、`arrow_left`、`arrow_right` | | 操作 | `space`、`key_e` | 任何其他事件类型、字段或按键,在 `world_setup` 之前发送 `user_action` 或 `input`,或者持续大量发送事件(超出约 120 个的突发量后,约为每秒 60 个),都会以关闭码 `1008`(策略违规)结束会话。被拒绝的消息中的任何内容都不会到达模型。 模型自身的事件会通过同一个 socket 返回。会话会在以下情况结束: - 在模型的 `interaction.completed` 事件之后,关闭码为 `1000`; - 在模型的 `error` 事件之后,关闭码为提供商的关闭码或 `1011`; - 达到 **120 秒**的会话上限时(如果你的余额可支撑的时间更短,则会更早),关闭码为 `1000`。 模型事件中的错误文本在到达你之前可能会被替换为通用消息。 ```python Python # Python 3.10+ # 安装:python -m pip install "websockets>=13" # 运行:COMFY_API_KEY=comfyui-... python genie.py import asyncio import json import os from websockets.asyncio.client import connect from websockets.exceptions import InvalidStatus URL = "wss://api.comfy.org/v2/realtime/google/google/genie-4" async def receive(ws): async for message in ws: if isinstance(message, bytes): print(f"<- {len(message)} bytes") continue event = json.loads(message) print("<-", event.get("event_type")) async def main(): try: ws = await connect( URL, additional_headers={"X-API-Key": os.environ["COMFY_API_KEY"]}, max_size=None, ) except InvalidStatus as err: # 升级被拒绝:响应体是包含 detail、error_type 和 code 的 JSON。 print(err.response.status_code, err.response.body.decode(errors="replace")) return async with ws: reader = asyncio.create_task(receive(ws)) async def send(event): await ws.send(json.dumps(event)) await send({ "event_type": "world_setup", "world_prompt": {"text": "A quiet harbor town at sunset, seen from the docks"}, }) await send({"event_type": "user_action", "action": "key_down", "input": "key_w"}) await asyncio.sleep(2) await send({"event_type": "user_action", "action": "key_up", "input": "key_w"}) await send({"event_type": "user_action", "action": "key_click", "input": "arrow_left"}) await send({"event_type": "input", "content": [{"type": "text", "text": "Make it start to rain"}]}) await asyncio.sleep(5) await send({"event_type": "interaction.complete"}) await reader print("closed:", ws.close_code) asyncio.run(main()) ``` ```js Browser // 一个已使用 Comfy 账号登录的页面。getIdToken() 是你的 Firebase 认证 // 调用;令牌通过子协议 offer 传输,绝不会出现在 URL 中。 const idToken = await auth.currentUser.getIdToken(); const ws = new WebSocket( "wss://api.comfy.org/v2/realtime/google/google/genie-4", ["comfy-realtime.v1", "comfy-bearer." + idToken], ); ws.addEventListener("open", () => { ws.send(JSON.stringify({ event_type: "world_setup", world_prompt: { text: "A quiet harbor town at sunset, seen from the docks" }, })); }); // 将十个受支持的按键映射为 Genie 4 的按键名。 const keys = { KeyW: "key_w", KeyS: "key_s", KeyA: "key_a", KeyD: "key_d", ArrowUp: "arrow_up", ArrowDown: "arrow_down", ArrowLeft: "arrow_left", ArrowRight: "arrow_right", Space: "space", KeyE: "key_e", }; for (const [type, action] of [["keydown", "key_down"], ["keyup", "key_up"]]) { window.addEventListener(type, (e) => { const input = keys[e.code]; if (!input || e.repeat || ws.readyState !== WebSocket.OPEN) return; ws.send(JSON.stringify({ event_type: "user_action", action, input })); }); } ws.addEventListener("message", (e) => { if (typeof e.data === "string") console.log("<-", JSON.parse(e.data).event_type); }); ws.addEventListener("close", (e) => console.log("closed", e.code)); ``` 浏览器示例会为每次物理按键发送一个 `key_down` 和一个 `key_up`,并跳过自动重复,因此远低于事件速率限制。 ### Grok Voice `xai/grok-voice/realtime` 是一种语音到语音的对话。会话使用 fal 的 realtime 传输格式:以经过 [MessagePack](https://msgpack.org) 编码的二进制帧发送每个事件;响应以 MessagePack 二进制帧或 JSON 文本帧的形式返回。其中的事件是 xAI 的 realtime 语音事件。 你可以发送以下客户端事件:`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` 和 `response.cancel`。每个事件只能携带其文档中列出的字段。 - 工具仅限于由客户端执行的 `function` 工具。诸如 MCP 服务器以及网页或 X 搜索之类的服务器端工具会被拒绝。 - 事件中任何位置出现图像和视频内容都会被拒绝。 - 如果设置了 `session.model`,它必须是 `grok-voice-latest`、`grok-voice-3.0` 或 `grok-voice-2.0`。 违反这些规则的消息不会被转发,并且会以关闭码 `1008` 结束会话。会话上限为 **30 分钟**,并会事先缩短为你的余额所能覆盖的时长;达到上限时,连接会被关闭且不发送关闭帧。 一个 Grok Voice 会话的费用为 **每秒 $0.0011869**(约每分钟 $0.0712;按 211 积分 = $1 计算,约每秒 0.25 积分或每分钟 15 积分)。无论音频是否在传输,只要套接字处于打开状态,整个时间段都会计费。 ```js Node // Node 20+ // 安装:npm install ws @msgpack/msgpack // 运行:COMFY_API_KEY=comfyui-... node grok-voice.mjs import { decode, encode } from "@msgpack/msgpack"; import WebSocket from "ws"; const ws = new WebSocket("wss://api.comfy.org/v2/realtime/fal/xai/grok-voice/realtime", { headers: { "X-API-Key": process.env.COMFY_API_KEY }, }); const send = (event) => ws.send(Buffer.from(encode(event))); ws.on("unexpected-response", (_req, res) => { let body = ""; res.on("data", (chunk) => (body += chunk)); res.on("end", () => console.error("refused:", res.statusCode, body)); }); ws.on("open", () => { send({ type: "session.update", session: { voice: "Ara", instructions: "Answer in one short sentence.", turn_detection: { type: null }, }, }); send({ type: "conversation.item.create", item: { type: "message", role: "user", content: [{ type: "input_text", text: "Say hello." }] }, }); send({ type: "response.create" }); }); ws.on("message", (data, isBinary) => { const event = isBinary ? decode(data) : JSON.parse(data.toString()); console.log("<-", event.type); if (event.type === "response.done" || event.type === "error") ws.close(1000); }); ws.on("close", (code) => console.log("closed", code)); ``` 如果要发送语音而不是文本,请使用 `input_audio_buffer.append`(base64 编码的 `audio`)流式发送音频,然后调用 `input_audio_buffer.commit` 和 `response.create`。 ## WebRTC 世界模型 `fal-ai/abot-world-0` 和 `fal-ai/lingbot-world-2` 通过 WebRTC 传输视频。媒体流以点对点方式**直接在浏览器与 fal 之间传输**;Router 只处理建立连接所需的 HTTP 信令,并附加 fal 的凭据,因此你的客户端永远不会持有这些凭据。 每次信令调用都是一个发往 `https://api.comfy.org/v2/realtime/wma/fal` 的 `POST` 请求,需携带你的 Comfy 凭据、JSON 请求体,并在 `x-fal-target-url` 请求头中指定真实目标地址。这是 fal 的 JavaScript 客户端使用的代理约定,因此你可以将该客户端的代理设置指向此路由。仅接受以下目标地址;其他任何地址都会被拒绝,并返回 `400` 和 `code: router.realtime.wma_target_rejected`: | `x-fal-target-url` | 请求体 | 用途 | | --- | --- | --- | | `https://wma.fal.run/ice` | `{"app_id": ""}` | 获取 ICE 服务器。不会创建会话且不计费。 | | `https://wma.fal.run/session` | 包含 `"app_id": ""` | 打开会话。响应会携带其 `session_id`。 | | `https://wma.fal.run/session/heartbeat` | `{"session_id": ""}` | 保持会话活跃。 | | `https://wma.fal.run/session/close` | `{"session_id": ""}` | 结束会话。使用相同请求体的 `DELETE /v2/realtime/wma/fal` 也会执行相同操作。 | 请求体必须是一个不超过 64 KiB、且不含重复键的 JSON 对象。`app_id` 和 `session_id` 必须严格按此拼写;大小写不同会被拒绝并返回 `400`。 ```bash # 获取世界模型的 ICE 服务器(不创建会话,不收费)。 curl -X POST https://api.comfy.org/v2/realtime/wma/fal \ -H "X-API-Key: $COMFY_API_KEY" \ -H "Content-Type: application/json" \ -H "x-fal-target-url: https://wma.fal.run/ice" \ -d '{"app_id": "fal-ai/lingbot-world-2"}' ``` ```js // 在已登录 Comfy 账户的浏览器中发送心跳并关闭会话。 const signal = (target, body) => fetch("https://api.comfy.org/v2/realtime/wma/fal", { method: "POST", headers: { Authorization: `Bearer ${idToken}`, "Content-Type": "application/json", "x-fal-target-url": target, }, body: JSON.stringify(body), }); const beat = setInterval( () => signal("https://wma.fal.run/session/heartbeat", { session_id: sessionId }), 5000, ); // 当用户停止时:先断开对等连接,然后关闭会话。 clearInterval(beat); peerConnection.close(); const res = await signal("https://wma.fal.run/session/close", { session_id: sessionId }); console.log(await res.json()); // { session_id, closed: true, settled: true | false } ``` ### 会话生命周期与计费 - **最长时长。** 每个会话最多运行 **480 秒**。 - **心跳。** 每 5 秒发送一次,与 fal 的客户端行为一致。Router 每个会话每秒最多转发一次;更快的心跳会被拒绝,并返回 `429` 和 `Retry-After: 1`。仅当 `session_id` 由你的账户打开且尚未关闭时,心跳和关闭请求才会被接受;否则会返回 `404` 和 `code: router.realtime.wma_session_not_found`。 - **计费。** 会话从打开时起按秒计费,直到最后一次心跳后 5 秒为止,最长不超过 480 秒。关闭会话会立即结算账单;心跳停止超过 15 秒的会话会自行结算。关闭响应中的 `settled: false` 表示账单仍在最终确认中,稍后即会生成。 - **打开时检查余额。** Router 无法在点对点会话开始后将其停止,因此打开会话要求余额足以覆盖本会话完整的 480 秒,以及你的工作区已经打开的每个 WebRTC 会话的完整时长。如果余额不足,`/session` 会被拒绝,并返回 `402` 和 `code: router.realtime.insufficient_credits`。这是一次检查,不是预留:会话运行期间,其他消费仍可能从同一余额中扣除。 - **并发会话。** 一个工作区同一时间最多可持有 **2** 个 WebRTC 世界模型会话。已关闭的会话会保留其名额,直到其打开约 480 秒后(外加一个短暂的结算窗口),因此快速关闭再重新打开可能会被拒绝,并返回 `429` 和 `code: router.realtime.concurrency_limit`;请等待响应中指定的 `Retry-After`。 当 fal 本身对信令调用返回错误时,Router 会原样透传 fal 的状态码和响应体。 ## 错误 被拒绝的升级或信令调用会返回 HTTP 状态码和 JSON 响应体,其中包含 `detail`、`error_type` 以及用于说明原因的 `code`。请根据 `code` 或 `error_type` 进行分支判断,而不要依据 `detail`。一旦 WebSocket 会话已打开,问题则改为通过关闭代码报告。 | 状态码 | `code` | 含义 | | --- | --- | --- | | `400` | `router.realtime.subprotocol_required` | 一个 `comfy-bearer.` offer 抵达时没有携带 `comfy-realtime.v1`。 | | `401` | | 没有有效的凭据。 | | `402` | `router.realtime.insufficient_credits` | 工作区余额过低,无法开启会话。 | | `403` | `router.realtime.model_unavailable` | 该模型对你的账户不可用。 | | `403` | `router.realtime.account_blocked` | 账户已被封禁。 | | `404` | `router.realtime.model_not_allowed` | 此路由不提供该模型。请检查路径和模型 id。 | | `426` | `router.realtime.upgrade_required` | WebSocket 路由收到了普通 HTTP 请求。请检查是否有代理剥离了 `Upgrade` 和 `Connection` 请求头。 | | `429` | `router.realtime.rate_limited` | 请求过多,或提供商已达容量上限。请等待 `Retry-After`。 | | `429` | `router.realtime.session_already_live` | 你的工作区已有一个活跃的 WebSocket 会话。 | | `429` | `router.realtime.concurrency_limit` | 并发会话过多。请稍后重试。 | | `503` | `router.realtime.shutting_down` | 处理该请求的服务器正在重启。请重试。 | 升级过程以及 `/ice` 和 `/session` 信令调用,会消耗与其他 Router 调用相同的按调用方计算的[请求额度](/zh/development/comfy-router/limitations#请求按调用方进行速率限制)。 | 关闭代码 | 含义 | | --- | --- | | `1000` | 正常结束:模型已完成,或 Genie 4 会话达到其上限。 | | `1006` | 没有收到关闭帧。Router 侧的原因包括 Grok Voice 会话达到时间上限、积分用完或账户被封禁;网络中断或代理超时看起来也一样。此代码并非由 Router 发送;连接断开时由你的客户端上报。 | | `1008` | 客户端消息违反了模型的规则(参见上文各模型)。 | | `1011` | 模型报告了错误。 | | `1012` | 服务器正在重启。请打开新会话。 | ## 下一步 Router 支持的功能,以及其超时时限和请求速率限制。 费率与计费选项。