---
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 支持的功能,以及其超时时限和请求速率限制。
费率与计费选项。