实时语音合成 WebSocket API 参考

1. run-task —— 开启任务

发送时机：连接建立后的第一帧。

响应事件：成功返回 task-started，失败返回 task-failed。

数量限制：一条连接同时只允许 1 个任务；上一个任务结束后可以用新 task_id 再次发送。

payload 顶层

parameters —— 音频参数

parameters —— 功能参

pronunciation 等发音控制是否生效取决于音色对应的模型。

"replace" 临时规则 ≤ 128 条；规范紧凑 JSON 的 UTF-8 体积 ≤ 16 KiB 。

enable_ssml=true 时不能携带 vocabulary_id

示例

{
  "header": {
    "action": "run-task",
    "task_id": "550e8400-e29b-41d4-a716-446655440000",
    "streaming": "duplex"
  },
  "payload": {
    "parameters": {
      "voice": "9f2a1c4e-7b30-4d51-8a6c-2e5f1b8d0a37",
      "format": "mp3",
      "vocabulary_id": "123e4567-e89b-42d3-a456-426614174000",
      "hot_fix": {
        "replace": [
          {"ConvAI": "康维智能"},
          {"VIP": "贵宾"}
        ]
      }
      "sample_rate": 22050,
      "volume": 50,
      "rate": 1.0,
      "pitch": 1.0,
      "word_timestamp_enabled": true,
      "language_hints": ["zh"],
      "seed": 1024
    },
    "input": {}
  }
}

2. continue-task —— 增量发送文本

发送时机：收到 task-started 之后，可多次发送。

响应事件：result-generated + BINARY 音频帧（凑够一句时）。文本不足一句时无下行事件。

数量限制：单次 ≤ 20,000 字符（按原文计），单任务累计 ≤ 200,000 字符。enable_ssml=true 时全任务只允许一次。

{
  "header": {
    "action": "continue-task",
    "task_id": "550e8400-e29b-41d4-a716-446655440000",
    "streaming": "duplex"
  },
  "payload": { "input": { "text": "你好，欢迎使用语音合成服务。" } }
}

约束

• 两次 continue-task 间隔必须 < 20 秒，否则 task-failed(IdleTimeout)，连接保留可发新任务。

• 服务端按序透传并自动分句；不足一句的文本会被引擎缓存，直到凑够句子、收到 flush 或收到 finish-task。

• 缺 input.text 报 InvalidParameter: payload.input.text is required；空串 "" 被接受但不产生音频。

• 中文长文本注意：上游按 UTF-16 计数，中文每字占 2 字节，因此单次实际上限约 10,000 个中文字，超出时返回 InvalidParameter。

3. finish-task —— 结束任务（不可省略）

发送时机：文本全部发完之后。

响应事件：剩余 BINARY 音频帧，最后是 task-finished。

正常结束

{
  "header": { "action": "finish-task", "task_id": "550e8400-...", "streaming": "duplex" },
  "payload": { "input": {} }
}

• 服务端先刷净 TN 缓冲（若开启），再由引擎强制合成所有缓存内容（含不足一句的尾巴）。

• 发送后必须继续接收音频，直到 task-finished。

• 服务端对 finish-task 之后的合成等待无超时，长文本不会被截断。

取消任务（directive: cancel）

{
  "header": { "action": "finish-task", "task_id": "550e8400-...", "streaming": "duplex" },
  "payload": { "input": { "directive": "cancel" } }
}

• 与正常结束语义相反：立即返回 task-finished，不再输出后续音频，丢弃未合成的缓存内容。

• 取消后可以在同一条连接上重新发起新任务，无需重连。

• 下发的 usage.characters 为 0。

• 对应百炼 SDK 的 streamingCancel() / streaming_cancel()。

取消不代表不计费。取消前已经送入引擎的文本仍会计入用量，详见《计费规则》。

4. flush —— 强制合成缓存文本

用途：大模型流式输出场景中，不足一句的文本会一直被缓存不出声；flush 强制合成已缓存内容，让残句立即出声。

有两种等价写法，语义完全相同，区别只在协议模式是否接受：

写法 A：continue-task + input.flush=true（推荐，两种模式都支持）

百炼 SDK 的 streaming_flush() 发出的就是这种帧。注意 input 里不带 text。

{
  "header": { "action": "continue-task", "task_id": "550e8400-...", "streaming": "duplex" },
  "payload": { "input": { "flush": true } }
}

行为

• 先刷出 TN 缓冲（若开启），再让引擎强制合成；随后立即收到该残句的 result-generated + BINARY 音频帧。

• 任务仍在进行，可继续 continue-task。

• 无待合成内容时为安全空操作（无任何下行事件）。

• 每次 flush 形成一次韵律断句，频繁 flush 会让听感更碎，建议仅在确需压低出声延迟时使用。

• 与 word_timestamp_enabled 互斥：开启字级时间戳后发 flush 报 InvalidParameter（分段会让时间戳无法连续化）。

• 尾部残句本身不会丢：finish-task 一定会刷净所有缓存文本，不需要先 flush 再结束。

1. task-started —— 任务确认

{
  "header": { "event": "task-started", "task_id": "550e8400-...", "attributes": {} },
  "payload": {}
}

收到此事件后方可发送 continue-task。

2. result-generated —— 句级元数据

{
  "header": { "event": "result-generated", "task_id": "550e8400-..." },
  "payload": {
    "output": {
      "type": "sentence-end",
      "original_text": "你好，欢迎使用语音合成服务。",
      "sentence": {
        "index": 0,
        "words": [
          { "text": "你", "begin_index": 0, "end_index": 1, "begin_time": 0,   "end_time": 263 },
          { "text": "好", "begin_index": 1, "end_index": 2, "begin_time": 263, "end_time": 520 }
        ]
      }
    },
    "usage": { "characters": 14 }
  }
}

output.type 取值

字段说明

3. BINARY 音频帧

• 按 run-task 指定的 format / sample_rate 编码，紧跟在 type=sentence-synthesis 的 result-generated 之后到达。

• sentence-begin / sentence-end 仅为元数据，其后没有音频帧。

• 按接收顺序追加播放或写文件即可，无需重排。

• format=pcm 为裸 PCM（int16 小端、单声道），保存为文件需自行补 WAV 头。

4. task-finished —— 任务结束

{
  "header": {
    "event": "task-finished",
    "task_id": "550e8400-...",
    "attributes": {
      "request_uuid": "a1f5c7e93b8d4e2f9c0a6b1d7e4f8c25",
      "upstream_request_uuid": "9c0a6b1d-7e4f-8c25-a1f5-c7e93b8d4e2f",
      "session_id": "3f8a1c92-0d4e-4b77-9c31-6a5f2e8b4d10"
    }
  },
  "payload": { "usage": { "characters": 42 } }
}

为空的字段不输出（而非输出 null），请容忍键缺失。

收到此事件表示任务完整结束、音频已全部传输，可关闭连接或复用发起新任务。

5. task-failed —— 任务失败

{
  "header": {
    "event": "task-failed",
    "task_id": "550e8400-...",
    "error_code": "TextTooLong",
    "error_message": "Text too long: text length 30000 exceeds 20000 per continue-task",
    "attributes": {
      "request_uuid": "a1f5c7e93b8d4e2f9c0a6b1d7e4f8c25",
      "session_id": "3f8a1c92-0d4e-4b77-9c31-6a5f2e8b4d10"
    }
  },
  "payload": {
    "error": {
      "code": "TextTooLong",
      "message": "Text too long: text length 30000 exceeds 20000 per continue-task",
      "type": "client_error"
    }
  }
}

6. connected —— 平台扩展帧（仅扩展模式）

严格模式（默认）不下发此帧。 仅当握手声明 ?protocol=extended 时下发，且不走 header / payload 信封。

{
  "event": "connected",
  "userId": "1405573632598746",
  "workspaceId": "llm-xxxxxxxx",
  "sessionId": "3f8a1c92-0d4e-4b77-9c31-6a5f2e8b4d10",
  "requestId": "a1f5c7e93b8d4e2f9c0a6b1d7e4f8c25",
  "message": "WebSocket connected, gateway auth passed"
}

主要用途是在建连阶段就拿到 sessionId / requestId 便于排障。message 仅供人看，请勿用于程序判断。

约束速查

音色

voice 必须是平台音色 ID，即音色管理界面获取到的音色ID（形如 9f2a1c4e-7b30-4d51-8a6c-2e5f1b8d0a37）。

文本归一化（TN）

把文本中的数字、日期、时间、金额、电话号码、单位符号等书面写法转成口语读法后再合成，避免「12345」被逐字念错。

• 默认关闭，通过 X-TTS-TN: enable 或 ?tn=enable 开启，会话级生效，连接内所有任务共享。

• 流式行为：TN 逐字符喂入归一化管道，含数字 / 字母的片段会缓冲到标点边界才输出。因此句子请带句末标点（。！？；）；残句要立即出声需发 flush；finish-task 一定会刷净缓冲，尾部文本不会丢。

• fail-open：归一化组件不可用时自动退回原文透传，不报错、不断连，你无需为 TN 写错误分支。

开启 TN 后的口径变化

若你需要把音频时间戳映射回原始输入文本下标，请勿开启 TN（服务端不下发原文与归一化文本的映射关系）。

与 enable_ssml 不建议同开（TN 会处理标签内的数字）；与 word_timestamp_enabled 可同开。

超时矩阵

重要：心跳（ping / pong）不重置业务空闲计时。纯心跳的空闲连接仍会在 60s 被回收 —— 心跳只维持链路不被中间代理断开，与业务资源回收是两个独立机制。

并发限制

• 网关按账号维度限制同时在线的 WebSocket 连接数：连接建立算一路，连接关闭即释放一路。

• 超限时握手返回 HTTP 429（浏览器表现为 1006）；连接升级后被拒以关闭码 4429 表达。

• 默认额度为 5 路：同一工作空间同时在线的 WebSocket 连接数上限为 5。连接建立即占用一路，连接关闭即释放一路。

• 空闲连接同样占用额度。挂着不合成的连接不会自动让出槽位，用完请主动关闭。

• 需要提升并发额度请联系平台。

业务错误码（task-failed）

type 只有两种：client_error 需要改参数或调用方式，重试无意义；server_error 可退避重试。

WebSocket 关闭码

握手阶段失败没有应用层 Close 帧：凭证缺失 / 无效返回 401，protocol 取值非法返回 400，并发限流返回 429。浏览器一律只能观察到 1006，因此握手 URL 请始终携带 requestId 便于事后定位。