实时WebSocket

按 40 毫秒一帧连续推送 PCM,服务端回以同节拍的人声帧。首个回帧大约在 1 秒后到达,其余一路等节奏。适合会议、直播、语音助手前置。

WS /v1/audio-isolation/realtime 稳定 v1 更新于 2026-04

输入 · PCM 帧流输出 · 对齐的人声帧

/realtime

握手

限制与约束

帧大小、采样率、通道、位深全部锁死。帧尺寸错了就会收到 bad_request 并被关闭(WS close code 1008)。

帧率

40ms / 帧

握手时 frame_ms 字段填 40(部分部署支持 20)。

采样率

16kHz

input/output 均为 16 kHz。不支持其他采样率。

通道

mono

单声道 · int16 little-endian。

帧字节数

1280字节

16000 × 40ms × 2 bytes(int16)= 1280。

性能指标

待补充 — 会在生产硬件上给出稳态单连接的额外延迟、并发连接上限、CPU/GPU 负载。首帧回传与模型自带的 lookahead 相关,大约 1 秒。

首帧延迟

≈ 1s

模型 lookahead(测试中)

并发连接

—

单实例上限(测试中)

冷启动

—

模型加载时间(测试中)

资源占用

—

RAM / VRAM(测试中)

在线体验

选一个样例,浏览器在本地把它重采样为 16 kHz 单声道 int16,按 40 ms 一帧推给 WebSocket,边推边把回帧累积成可播的人声。走的是真的 WebSocket 连接(getWsBase()),完整协议握手可见。

实时 · WS /v1/audio-isolation/realtime

测试音频 —

点击上传 / 拖拽音频

任何格式 · 浏览器会重采样到 16 kHz mono

示例: clean-speech quiet-speech speech-2

协议 read-only

sample_rate: 16000
frame_ms: 40
frame bytes: 1280

输出 + 协议日志 —

选好音频后点 启动 WebSocket

⌘ / Ctrl + ↵ 快捷提交

协议

单连接、单协程。握手成功后进入帧循环;任意一端发 end 后服务端回 end_ack 并以 close 1000 关闭。

消息序列

client ↔ server · JSON text + binary PCMorder

// 1. 客户端: text, JSON
{"type": "start", "sample_rate": 16000, "frame_ms": 40}

// 2. 服务端: text, JSON
{"type": "ready"}

// 3. 客户端 → 服务端: 连续 binary 帧
<1280 bytes · PCM int16 LE · mono · 16 kHz>
<1280 bytes · ...>
...

// 4. 服务端 → 客户端: 从第 ~25 帧开始回 binary(模型 lookahead)
<1280 bytes · PCM int16 LE · mono · 16 kHz · 人声>
...

// 5. 客户端: text, JSON — 结束
{"type": "end"}

// 6. 服务端: text, JSON, 随后 close 1000
{"type": "end_ack"}

start 字段

字段	类型	要求	说明
type	"start"	必填	字面量 `"start"`。其他值或缺失都会收到 `bad_request`。
sample_rate	int	必填	必须等于 `16000`,否则关闭 1008。
frame_ms	int	必填	必须等于 `40`(部分部署为 `20`)。

帧字节格式

binary framelayout

// 每帧精确 1280 字节 = 16000 × 40ms × 2。尺寸不对就关 1008。
PCM int16 LE · mono · 16 kHz

// 样本索引 [0, 640) 按时间顺序,最老的样本在最前。
// 不要把 stereo 通道交织塞进来,不要 float32,不要大端。

错误帧

server → client · text JSON + close codeerror envelope

{"type": "error", "code": "bad_request", "message": "frame must be 1280 bytes, got 640"}
// 紧接 WS close code: 1008(客户端问题)或 1011(服务端问题)

调用示例

关闭码

WebSocket 用 close code 报错,没有 HTTP 状态码。错误帧本身是 JSON 文本,紧接 close。

AI 集成 — 一键复制提示词

粘到 Claude / Cursor / ChatGPT,一分钟拿到完整的帧循环客户端。

AI-READY PROMPT

— tokens · 适配 Claude 4.7 & GPT-5

用 AI 快速集成

已在主流编码 Agent 上测试通过。包含完整接口契约、错误码和示例。粘贴后说 “用我的技术栈实现这个”。