豆包端到端实时语音大模型 API 对接文档

接口概述

/v1/realtime/volcengine/dialogue 提供豆包（Doubao）端到端实时语音大模型的 WebSocket 代理接入。客户端通过本接口与豆包 Realtime API 进行实时语音/文本对话，网关完全透传豆包的二进制协议帧，同时实现鉴权、渠道路由、用量计费和日志记录。

1. 官方文档

https://www.volcengine.com/docs/6561/1594356?lang=zh

2. 接口说明

2.1 连接地址

wss://{gateway_host}/v1/realtime/volcengine/dialogue?model=doubao-realtime

参数	必须	说明
`model`	是	模型名称，用于渠道路由匹配（当前只能是 `doubao-realtime`）

2.2 鉴权方式

支持以下任一方式传递 API Key：

方式一：Authorization Header（推荐）

Authorization: Bearer sk-your-token-key

方式二：Sec-WebSocket-Protocol（浏览器场景）

2.3 协议说明

本接口完全透传豆包的二进制 WebSocket 协议。客户端按照豆包官方文档构建和解析二进制帧即可，网关不对协议内容做任何修改。

3. 二进制协议概要

每个 WebSocket 帧由 Header（4字节） + Optional 字段 + Payload 组成。

3.1 Header 结构

字节	高 4 位	低 4 位	说明
0	Protocol Version	Header Size	固定 `0x11`（v1, 4字节头）
1	Message Type	Flags	见下表
2	Serialization	Compression	JSON=`0x10`, Raw=`0x00`, 无压缩
3	Reserved	Reserved	固定 `0x00`

3.2 Message Type

值	名称	说明
`0b0001`	FullClient	客户端发送文本事件
`0b0010`	AudioOnlyClient	客户端发送音频数据
`0b1001`	FullServer	服务端返回文本事件
`0b1011`	AudioOnlyServer	服务端返回音频数据
`0b1111`	Error	错误信息

3.3 Flags

值	含义
`0b0000`	无 sequence
`0b0001`	带正 sequence
`0b0011`	带负 sequence（最后一包）
`0b0100`	带 event ID

3.4 Optional 字段（当 flags 包含 event 时）

按顺序排列：

Event ID（4 字节 int32，大端序）

Session ID（4 字节长度 + N 字节内容）— 连接级事件（1,2,50,51,52）跳过

Connect ID（4 字节长度 + N 字节内容）— 仅事件 50,51,52 携带

3.5 Payload

4 字节长度（uint32 大端序）+ N 字节内容（JSON 或 raw 音频数据）。

4. 交互流程

客户端                              网关                              豆包上游
  |                                  |                                  |
  |--- WebSocket Upgrade ----------->|                                  |
  |                                  |--- WebSocket Connect ----------->|
  |                                  |    (X-Api-App-ID, Access-Key)    |
  |                                  |                                  |
  |--- StartConnection (event=1) --->|-------- 透传 ------------------>|
  |<-- ConnectionStarted (event=50) -|<------- 透传 -------------------|
  |                                  |                                  |
  |--- StartSession (event=100) ---->|-------- 透传 ------------------>|
  |    (tts/asr/dialog config)       |                                  |
  |<-- SessionStarted (event=150) ---|<------- 透传 -------------------|
  |                                  |                                  |
  |--- TaskRequest (event=200) ----->|-------- 透传 ------------------>|
  |    (audio PCM data)              |                                  |
  |<-- ASRResponse (event=451) ------|<------- 透传 -------------------|
  |<-- ChatResponse (event=550) -----|<------- 透传 -------------------|
  |<-- TTSResponse (event=352) ------|<------- 透传 -------------------|
  |<-- UsageResponse (event=154) ----|<------- 透传 + 解析计费 --------|
  |                                  |                                  |
  |--- FinishSession (event=102) --->|-------- 透传 ------------------>|
  |<-- SessionFinished (event=152) --|<------- 透传 -------------------|
  |                                  |                                  |
  |--- FinishConnection (event=2) -->|-------- 透传 ------------------>|
  |<-- ConnectionFinished (event=52) |<------- 透传 -------------------|
  |                                  |                                  |
  |                                  |--- 记录消费日志 (logs 表) -------|

5. 客户端事件

Event ID	名称	Payload	说明
1	StartConnection	`{}`	建立连接
2	FinishConnection	`{}`	断开连接
100	StartSession	JSON（见下方）	创建会话
102	FinishSession	`{}`	结束会话
200	TaskRequest	音频二进制数据	上传音频（PCM, 16kHz, int16, 单声道）
201	UpdateConfig	JSON	更新会话配置
300	SayHello	`{"content": "..."}`	发送问候语
400	EndASR	`{}`	音频输入结束信号（按键模式）
500	ChatTTSText	`{"start":bool,"content":"...","end":bool}`	指定文本合成音频
501	ChatTextQuery	`{"content": "..."}`	发送文本 query
502	ChatRAGText	`{"external_rag": "..."}`	外部 RAG 知识输入

5.1 StartSession Payload 示例

{
  "tts": {
    "speaker": "zh_female_vv_jupiter_bigtts",
    "audio_config": {
      "channel": 1,
      "format": "pcm",
      "sample_rate": 24000
    }
  },
  "asr": {
    "extra": {
      "end_smooth_window_ms": 1500
    }
  },
  "dialog": {
    "bot_name": "豆包",
    "system_role": "你是一个有帮助的助手。",
    "speaking_style": "说话简洁明了。",
    "extra": {
      "strict_audit": false,
      "input_mod": "audio",
      "model": "1.2.1.1"
    }
  }
}

dialog.extra.model 必传，取值：

1.2.1.1 — O2.0 版本

2.2.0.0 — SC2.0 版本

input_mod 取值：

audio — 麦克风实时输入（默认）

text — 纯文本输入

audio_file — 录音文件输入

keep_alive — 麦克风含静音按键

push_to_talk — 按键说话

tts.audio_config.format 取值：

pcm — 32bit float LE, 24kHz（默认）

pcm_s16le — 16bit signed int LE, 24kHz

6. 服务端事件

Event ID	名称	说明
50	ConnectionStarted	连接建立成功
51	ConnectionFailed	连接失败
52	ConnectionFinished	连接结束
150	SessionStarted	会话创建成功，返回 `dialog_id`
152	SessionFinished	会话结束
153	SessionFailed	会话失败
154	UsageResponse	用量信息（每轮对话后返回）
350	TTSSentenceStart	TTS 句子开始
351	TTSSentenceEnd	TTS 句子结束
352	TTSResponse	TTS 音频数据（AudioOnlyServer 类型）
359	TTSEnded	一轮音频合成结束
450	ASRInfo	检测到用户说话
451	ASRResponse	语音识别结果
459	ASREnded	用户说话结束
550	ChatResponse	模型文本回复
559	ChatEnded	模型回复结束
599	DialogCommonError	对话错误

6.1 UsageResponse Payload

{
  "usage": {
    "input_text_tokens": 1032,
    "input_audio_tokens": 548,
    "cached_text_tokens": 943,
    "cached_audio_tokens": 110,
    "output_text_tokens": 10,
    "output_audio_tokens": 52
  }
}

7. 代码示例

7.1 Go 客户端

7.2 Python 客户端

7.3 浏览器调试页面

项目提供了 Web 调试页面，位于 py/doubao_realtime/：

支持麦克风语音输入和文本输入两种模式，实时显示所有事件日志。

8. 可用音色

O / O2.0 版本精品音色

音色 ID	说明
`zh_female_vv_jupiter_bigtts`	vv，活泼灵动女声（默认）
`zh_female_xiaohe_jupiter_bigtts`	xiaohe，甜美活泼女声
`zh_male_yunzhou_jupiter_bigtts`	yunzhou，清爽沉稳男声
`zh_male_xiaotian_jupiter_bigtts`	xiaotian，清爽磁性男声

SC / SC2.0 版本克隆音色

SC 版本使用 ICL_ 前缀，SC2.0 版本使用 saturn_ 前缀。详见豆包官方文档。

9. 错误码

错误码	说明
42000020	StartSession 参数缺失（asr.extra 或 tts.extra 为空）
45000003	超过 10 分钟无交互，服务端断开
50000000	模型推理出错
52000042	音频流超时，建议设置 `input_mod: keep_alive`
55000001	未正常发送 FinishSession

10. 注意事项

音频输入格式：PCM, 单声道, 16kHz, int16, 小端序。推荐 20ms 一包（640 字节）发送。

Session 复用：发送 FinishSession 后可复用 WebSocket 连接，重新发送 StartSession 开始新会话。

model 字段必传：dialog.extra.model 必须在 StartSession 中指定，1.2.1.1（O2.0）或 2.2.0.0（SC2.0）。

断开连接：建议按 FinishSession → FinishConnection → Close WebSocket 顺序断开，避免上游报错。

计费说明：网关从上游 UsageResponse(event=154) 事件中实时提取 token 用量进行计费，每轮对话结束后上游会返回该事件。

豆包端到端实时语音

豆包端到端实时语音大模型 API 对接文档#

接口概述#

1. 官方文档#

2. 接口说明#

2.1 连接地址#

2.2 鉴权方式#

2.3 协议说明#

3. 二进制协议概要#

3.1 Header 结构#

3.2 Message Type#

3.3 Flags#

3.4 Optional 字段（当 flags 包含 event 时）#

3.5 Payload#

4. 交互流程#

5. 客户端事件#

5.1 StartSession Payload 示例#

6. 服务端事件#

6.1 UsageResponse Payload#

7. 代码示例#

7.1 Go 客户端#

7.2 Python 客户端#

7.3 浏览器调试页面#

8. 可用音色#

O / O2.0 版本精品音色#

SC / SC2.0 版本克隆音色#

9. 错误码#

10. 注意事项#