豆包端到端实时语音大模型API即RealtimeAPI支持低延迟、多模式交互，可用于构建语音到语音的对话工具。该API支持中文和英语两大语种，目前只支持WebSocket协议连接到此API，同时支持客户边发送数据边接收数据的流式交互方式。

1.1 产品约束 #

1. 不同端到端模型版本的功能差异如下所示，其中未特别标注的功能，均为所有版本通用支持

• O 版本代表 Omni，多模态模型路线；SC 版本代表 Strong Character，角色扮演模型路线，主要强化人设表达和拟人化互动能力
  • 当前 O 版本与 SC 版本已停止独立迭代维护，产品能力将逐步收敛至对应的 2.0 版本，并以后者作为后续主推方向
• O版本和SC版本都支持客户配置System Prompt，但是具体的配置字段会存在差异：
  • O版本以及O2.0版本可以配置bot_name、system_role、speaking_style字段，参考人设部分
  • SC版本以及SC2.0版本可以配置character_manifest字段，参考角色描述部分
• O2.0 版本相较于 O 版本的主要优化点：
  • 整体能力升级：显著提升模型的推理能力与基础语音理解、生成能力
  • 唱歌能力增强：引入合规版权曲库，支持更高质量、更丰富的演唱表现
  • 音频级热修复：支持在线修复 TN 转写与发音问题，提升问题响应效率，降低版本发布依赖。
• SC2.0 版本相较于 SC 版本的主要优化点：
  • 角色演绎能力提升：显著增强模型的角色塑造与拟人化表达能力
  • 角色控制能力增强：完善角色控制指令体系，模型输出文本可包含角色相关的动作与表情描述
  • 音色克隆能力升级：提升音色克隆的相似度与稳定性
  • 音频级热修复：支持在线修复 TN 转写与发音问题，提升问题响应效率，降低版本发布依赖。

2. 客户端上传音频格式要求PCM（脉冲编码调制，未经压缩的的音频格式）、单声道、采样率16000、每个采样点用int16表示、字节序为小端序。
   1. 除此之外，工程链路升级支持客户端麦克风输入音频opus格式，服务内部会转为pcm格式再进行识别处理

{
    "asr": {
        "audio_info": {
            "format": "speech_opus",
            "sample_rate": 16000,
            "channel": 1
        }
    }
}

3. 服务端默认返回的是 OGG 封装的 Opus 音频，兼顾压缩效率与传输性能
4. 若客户端在 StartSession事件中增加TTS配置，服务端可返回 PCM 格式的音频流。具体请求参数如下所示：
   • 单声道、24000Hz 采样率、32bit位深、字节序为小端序；

{
    "tts" : {
        "audio_config": {
            "channel": 1,
            "format": "pcm",
            "sample_rate": 24000
        }
    }
}

• 单声道、24000Hz 采样率、16bit位深、字节序为小端序；

{
    "tts" : {
        "audio_config": {
            "channel": 1,
            "format": "pcm_s16le",
            "sample_rate": 24000
        }
    }
}

5. 端到端模型O版本服务端已新增 4 个音色（O2.0版本音色名称保持不变），客户端需在 StartSession事件中的TTS 配置指定对应的发音人，默认为vv音色。
   1. zh_female_vv_jupiter_bigtts：对应vv音色，活泼灵动的女声，有很强的分享欲
   2. zh_female_xiaohe_jupiter_bigtts：对应xiaohe音色，甜美活泼的女声，有明显的台湾口音
   3. zh_male_yunzhou_jupiter_bigtts：对应yunzhou音色，清爽沉稳的男声
   4. zh_male_xiaotian_jupiter_bigtts：对应xiaotian音色，清爽磁性的男声
   5. en_male_tim_uranus_bigtts：Tim，美式英语，仅支持O2.0版本
   6. en_female_dacey_uranus_bigtts：Dacey，美式英语，仅支持O2.0版本
   7. en_female_stokie_uranus_bigtts：Stokie，美式英语，仅支持O2.0版本

{
    "tts": {
        "speaker": {{STRING}}
    }
}

6. 端到端模型SC版本服务端新增21个官方克隆音色，客户端在使用这些音色时候需要在StartSession事件中的TTS 配置指定对应的克隆音色。同时，角色描述在服务端已经配置好了，客户端在请求API时候无需配置character_manifest字段。

SC版本

1. ICL_zh_female_aojiaonvyou_tob
2. ICL_zh_female_bingjiaojiejie_tob
3. ICL_zh_female_chengshujiejie_tob
4. ICL_zh_female_keainvsheng_tob
5. ICL_zh_female_nuanxinxuejie_tob
6. ICL_zh_female_tiexinnvyou_tob
7. ICL_zh_female_wenrouwenya_tob
8. ICL_zh_female_wumeiyujie_tob
9. ICL_zh_female_xingganyujie_tob
10. ICL_zh_male_aiqilingren_tob
11. ICL_zh_male_aojiaogongzi_tob
12. ICL_zh_male_aojiaojingying_tob
13. ICL_zh_male_aomanshaoye_tob
14. ICL_zh_male_badaoshaoye_tob
15. ICL_zh_male_bingjiaobailian_tob
16. ICL_zh_male_bujiqingnian_tob
17. ICL_zh_male_chengshuzongcai_tob
18. ICL_zh_male_cixingnansang_tob
19. ICL_zh_male_cujingnanyou_tob
20. ICL_zh_male_fengfashaonian_tob
21. ICL_zh_male_fuheigongzi_tob

SC2.0版本

1. saturn_zh_female_aojiaonvyou_tob

2. saturn_zh_female_bingjiaojiejie_tob

3. saturn_zh_female_chengshujiejie_tob

4. saturn_zh_female_keainvsheng_tob

5. saturn_zh_female_nuanxinxuejie_tob

6. saturn_zh_female_tiexinnvyou_tob

7. saturn_zh_female_wenrouwenya_tob

8. saturn_zh_female_wumeiyujie_tob

9. saturn_zh_female_xingganyujie_tob

10. saturn_zh_male_aiqilingren_tob

11. saturn_zh_male_aojiaogongzi_tob

12. saturn_zh_male_aojiaojingying_tob

13. saturn_zh_male_aomanshaoye_tob

14. saturn_zh_male_badaoshaoye_tob

15. saturn_zh_male_bingjiaobailian_tob

16. saturn_zh_male_bujiqingnian_tob

17. saturn_zh_male_chengshuzongcai_tob

18. saturn_zh_male_cixingnansang_tob

19. saturn_zh_male_cujingnanyou_tob

20. saturn_zh_male_fengfashaonian_tob

21. saturn_zh_male_fuheigongzi_tob

22. 除了官方克隆音色之外，客户还可以在火山豆包语音控制台开通、上传音频训练自定义克隆音色等功能。

    1. 购买入口
       1. SC版本在豆包端到端实时语音大模型商品里面

2. SC2.0版本在豆包声音复刻模型2.0商品里面，在这里购买的音色能同时用于tts和实时语音

3. 需要注意的是：购买克隆音色之后目前是分钟级生效，即2分钟之后才可以发起音色注册请求

2. 注册克隆音色参考文档，和传统的声音复刻相比有如下注意事项：
   1. 端到端模型仅对中文有较好支持，其他语种效果暂时还不能保证
   2. 在端到端模型里注册克隆音色时候，强烈推荐带上对应的音频文本，保证模型克隆效果。另外，需要注意的是，训练音频对应的文本会在合成时候带到System Prompt里面提升克隆效果
   3. 注册端到端模型的复刻音色请求所需参数，未提及参数对端到端链路不生效无需填写
      1. {{Resource-Id}}： SC版本填写seed-icl-1.0；SC2.0版本填写seed-icl-2.0
      2. model_type参数SC版本无需填写；SC2.0版本需填写4

curl -L -X POST 'https://openspeech.bytedance.com/api/v1/mega_tts/audio/upload' \
-H 'Authorization: Bearer; your-access-key' \
-H 'Resource-Id: {{Resource-Id}}' \
-H 'Content-Type: application/json' \
-d '{
    "speaker_id": "S_123456",
    "appid": "12345678",
    "audios": [
        {
            "audio_bytes": "必填，二进制音频字节，需对二进制音频进行base64编码",
            "text":"必填，音频所对应的文本，可以让用户按照该文本念诵，服务会对比音频与该文本的差异。若差异过大会返回1109 WERError",
            "audio_format": "wav"
        }
    ],
    "model_type": 4, // 该参数仅SC2.0版本音色需要
    "source": 2
}'

8. 限流条件分为QPM和TPM，QPM全称query per minute，这里的query对应StartSession事件，即在一个AppID下面每分钟的StartSession事件不能超过配额值（默认60QPM）。TPM全称tokens per minute，即一分钟所消耗的全部token不能超过对应的配额值（默认10wTPM）。

1.2 最佳实践 #

1. 系统最初仅支持麦克风输入，现已逐步扩展，支持文本和录音文件作为输入源。具体说明如下：
   1. 麦克风输入
      1. 采用流式输入输出架构，音频会实时上传，推荐20ms一包发送服务端
      2. 客户端无需额外发送静音片段
   2. 麦克风（包含静音按键）输入
      1. 麦克风正常打开时候流式输入，音频实时上传【强烈推荐】20ms一包发送服务端
      2. 麦克风静音时候无法上传音频到服务端，需要指定如下参数避免音频流超时报错

{
    "dialog": {
        "extra": {
            "input_mod": "keep_alive"
        }
    }
}

3. 麦克风按键输入
   1. 产品交互形态为按下麦克风按键开始收音，音频实时上传【强烈推荐】​20ms一包发送服务端
   2. 此模式下无需补充静音，同时屏蔽掉服务端VAD，即依赖客户端告诉服务端音频发送结束，需要指定如下参数才会生效：

{
    "dialog": {
        "extra": {
            "input_mod": "push_to_talk"
        }
    }
}

4. 纯文本输入
   1. 支持直接以文本形式发起对话。
   2. 服务端会自动补充静音片段，保证流式链路的完整性。

{
    "dialog": {
        "extra": {
            "input_mod": "text"
        }
    }
}

5. 录音文件输入
   1. 支持将录音文件作为输入源，但是需要将录音文件改为流式发送，【强烈推荐】​发送20ms的音频包休眠20ms。
   2. 对于采样率 16k、位深 int16 的pcm音频而言，20ms 的音频包大小为 640 字节。
   3. 服务端同样会自动补充静音片段，保持与麦克风实时流式输入一致的处理逻辑。

{
    "dialog": {
        "extra": {
            "input_mod": "audio_file"
        }
    }
}

2. 在客户端发送 FinishSession 事件后，系统将不再返回任何事件。但客户端仍可复用与火山语音网关之间的 WebSocket 连接。若需发起新的会话，客户端需重新从 StartSession 事件开始。

3. 在没有对话需求时候，可以发送FinishSession事件结束会话。如果不想复用websocket连接，可以继续发送FinishConnection事件，释放对应的websocket连接。
4. 推荐客户端在事件的 optional 字段中携带 event 和 session ID，以降低开发成本，并将事件处理的复杂性交由火山语音服务端负责。

WebSocket是一种广泛支持的实时数据传输API，也是服务器应用程序中连接到豆包端到端实时语音大模型API的最佳选择。在客户服务器上集成此API时候，可以通过WebSocket直接连接到实时语音大模型API，具体鉴权参数可以在火山控制台获取。

2.1 ws连接详细信息 #

• 通过WebSocket建立连接需要以下连接信息：

• 在 websocket 握手成功后，会返回如下Response header

2.2 WebSocket二进制协议 #

豆包端到端实时语音大模型API使用二进制协议传输数据，协议由4字节的header、optioanl、payload size和payload三部分组成，其中：

• header用于描述消息类型、序列化方式以及压缩格式等信息
• optional可选字段
  • sequence字段
  • event字段，用于描述链接过程中状态管理的预定义事件
  • connect id size/ connect id字段，用于描述连接类事件的标识
  • session id size/ session id 字段，用于描述会话类事件的标识
  • error code: 仅用于错误数据包，描述错误信息
• payload size代表payload的长度
• payload是具体负载的内容，依据不同的消息类型装载不同的内容

二进制数据 #

Mesage Type

Message type specific flags #

Optional可选字段code、sequence、event取决于Message type specific flags，而connect id和session id取决于事件类型。如果设置对应flag请按照表格顺序进行二进制组装。目前支持的全集如下所示：

具体的payload size和payload #

payload可以放音频二进制数据，也可以放类似StartSession事件中的json数据。

错误帧payload

{
    "error": {{STRING}}
}

2.3 实时对话事件 #

通过WebSocket连接到豆包端到端实时语音大模型API之后，可以调用S2S模型进行语音到语音的对话。需要发送客户端事件来启动操作，并监听服务器事件以采取对应的操作。

客户端事件 #

{}

{
    "asr": {
        "extra": {
            "end_smooth_window_ms": {{INT}},
            "enable_custom_vad": {{BOOLEAN}},
            "enable_asr_twopass": {{BOOLEAN}},
            "boosting_table_id": {{STRING}},
            "boosting_table_name": {{STRING}},
            "regex_correct_table_id": {{STRING}},
            "regex_correct_table_name": {{STRING}},
            "context": {
                "hotwords": [
                    {"word": {{STRING}}}
                ],
                "correct_words": map[string]string{}
            }
        }
    }
}

{
    "dialog": {
        "bot_name": {{STRING}},
        "system_role": {{STRING}},
        "speaking_style": {{STRING}},
        "dialog_id": {{STRING}},
        "character_manifest": {{STRING}},
        "location": {
            "longitude": {{Float64}},
            "latitude": {{Float64}},
            "city": {{STRING}},
            "country": {{STRING}},
            "province": {{STRING}},
            "district": {{STRING}},
            "town": {{STRING}},
            "country_code": {{STRING}},
            "address": {{STRING}}
        },
        "dialog_context":[
           {
            "role": {{STRING}},
            "text": {{STRING}},
            "timestamp": {{INT}}
           }
        ]，
        "extra" : {
            "strict_audit": {{BOOLEAN}},
            "audit_response": {{STRING}},
            "enable_volc_websearch": {{BOOLEAN}},
            "volc_websearch_type": {{STRING}},
            "volc_websearch_api_key": {{STRING}},
            "volc_websearch_result_count": {{INT}},
            "volc_websearch_no_result_message": {{STRING}},
            "input_mod": {{STRING}},
            "enable_music": {{BOOL}},
            "enable_loudness_norm": {{BOOL}},
            "enable_conversation_truncate": {{BOOL}},
            "enable_user_query_exit": {{BOOL}},
            "model": {{STRING}}
        }
    }
}

{
    "tts": {
        "extra": {
            "explicit_dialect": {{STRING}},
            "aigc_metadata": {
                "enable": {{BOOL}}, // 是否启用隐式水印
                "content_producer": {{STRING}}, // 合成服务提供者的名称或编码
                "produce_id" : {{STRING}}, // 内容制作编号
                "content_propagator": {{STRING}}, // 内容传播服务提供者的名称或编码
                "propagate_id": {{STRING}} // 内容传播编号
            }，
            "tts_2.0_model": {{STRING}}
        },
        "audio_config": {
            "speech_rate": {{INT}},
            "loudness_rate": {{INT}}
        }
    }
}

{}

{
    "tts": {
        "speaker": {{STRING}},
        "audio_config": {
            "speech_rate": {{INT}},
            "loudness_rate": {{INT}}
        }
    },
    "dialog": {
        "bot_name": {{STRING}},
        "system_role": {{STRING}},
        "speaking_style": {{STRING}},
        "dialog_id": {{STRING}},
        "location": {
            "longitude": {{Float64}},
            "latitude": {{Float64}},
            "city": {{STRING}},
            "country": {{STRING}},
            "province": {{STRING}},
            "district": {{STRING}},
            "town": {{STRING}},
            "country_code":{{STRING}},
            "address": {{STRING}}
        }
    }
}

{
    "content": {{STRING}}
}

{}

{
    "start": {{BOOLEAN}},
    "content": {{STRING}},
    "end": {{BOOLEAN}}
}

{
    "content": {{STRING}}
}

{
    "external_rag": {{STRING}}
}

{
    "items":[
        {
            "role": {{STRING}},
            "text": {{STRING}},
            "timestamp": {{INT}}
        }
    ]
}

{
    "items":[
        {
            "item_id": {{STRING}},
            "text": {{STRING}}
        }
    ]
}

{
    "items":[
        {
            "item_id": {{STRING}}
        }
    ]
}

{
    "item_id": {{STRING}},
    "audio_end_ms": {{INT}}
}

{
    "items":[
        {
            "item_id": {{STRING}}
        }
    ]
}

{}

备注：

• Websocket阶段：在 HTTP 建立连接之后Upgrade
• 客户端在发送FinishSession事件之后，websocket连接不会断开，客户端可以继续复用，复用时候需要再发送一次StartSession事件，即重新初始化会话
• Message Type = 0b0001，Message type specific flags = 0b0100，StartConnection事件二进制帧对应的字节数组示例：
  • [17 20 16 0 0 0 0 1 0 0 0 2 123 125]
• Message Type = 0b0001，Message type specific flags = 0b0100，SessionID = 75a6126e-427f-49a1-a2c1-621143cb9db3，jsonPayload = {"dialog":{"bot_name":"豆包","dialog_id":"","extra":null}}，StartSession事件二进制帧对应的字节数组示例：

[17 20 16 0 0 0 0 100 0 0 0 36 55 53 97 54 49 50 54 101 45 52 50 55 102 45 52 57 97 49 45 97 50 99 49 45 54 50 49 49 52 51 99 98 57 100 98 51 0 0 0 60 123 34 100 105 97 108 111 103 34 58 123 34 98 111 116 95 110 97 109 101 34 58 34 232 177 134 229 140 133 34 44 34 100 105 97 108 111 103 95 105 100 34 58 34 34 44 34 101 120 116 114 97 34 58 110 117 108 108 125 125]

• ChatTTSText事件请求示例：
  • 第一包json示例

{
    "start": true,
    "content": "今天是",
    "end": false
}

• 中间包，用于流式上传待合成音频的文本

{
    "start": false,
    "content": "星期二。",
    "end": false
}

• 最后一包，若用户在音频播报过程中发起新的 query 导致中断，且合成音频的 end 包尚未发送，此时无需再下发该 end 包，以避免多余流程或状态异常。

{
    "start": false,
    "content": "",
    "end": true
}

• ChatRAGText事件请求中的external_rag是一个json数组字符串，对应的json描述：

{
    "title": {{STRING}},
    "content": {{STRING}},
}

服务端事件 #

{}

{
    "error": {{STRING}}
}

{}

{
    "dialog_id": {{STRING}}
}

{}

{
    "error": {{STRING}}
}

{
    "usage": {
        "input_text_tokens": {{INT}},
        "input_audio_tokens": {{INT}},
        "cached_text_tokens": {{INT}},
        "cached_audio_tokens": {{INT}},
        "output_text_tokens": {{INT}},
        "output_audio_tokens": {{INT}},
    }
}

{}

{
    "tts_type": {{STRING}},
    "text" : {{STRING}},
    "question_id": {{STRING}},
    "reply_id": {{STRING}},
}

{
    "question_id": {{STRING}},
    "reply_id": {{STRING}},
}

{
    "question_id": {{STRING}},
    "reply_id": {{STRING}},
    "status_code": "20000002",
}

{
    "question_id": {{STRING}}
}

{
    "results": [
      {
        "text": {{STRING}},
        "is_interim": {{BOOLEAN}}
      }
    ]
}

{}

{
  "content": {{STRING}},
  "question_id": {{STRING}},
  "reply_id": {{STRING}},
}

{
  "question_id": {{STRING}},
}

{
  "question_id": {{STRING}},
  "reply_id": {{STRING}},
}

{
    "items":[
        {
            "item_id": {{STRING}},
            "role": {{STRING}},
            "text": {{STRING}},
            "timestamp": {{INT}}
        }
    ]
}

{
    "message": "the following item ids are missing: 1,2,3"
}

{
    "items":[
        {
            "item_id": {{STRING}},
            "role": {{STRING}},
            "text": {{STRING}},
            "timestamp": {{INT}}
        }
    ]
}

{
    "status_code":40000010,
    "message":"empty conversation deleted messages"
}

{
    "items":[
        {
            "item_id": {{STRING}},
            "role": {{STRING}},
            "text": {{STRING}},
            "timestamp": {{INT}}
        }
    ]
}

{
    "status_code": {{STRING}},
    "message": {{STRING}}
}

备注：

• 服务器事件中json paylod可能会多返回一些字段，客户端无需关心
• Message type specific flags = 0b0100，session id =3c791a7d-227a-4446-993b-24f9e302cc98，TTSResponse事件示例：
  • [17 180 0 0 0 0 1 96 0 0 0 36 51 99 55 57 49 97 55 100 45 50 50 55 97 45 52 52 52 54 45 57 57 51 98 45 50 52 102 57 101 51 48 50 99 99 57 56 0 0 7 252 79 103 103 83 0 0 64 129 32 0 0 0 0 0 132 149 185 182 172 8 0 0 169 57 249 174 1 71 104 139 98 229 167 232 122 108 0 183 60 54 43 137 197 126 20 248 201 174]

Python示例 #

realtime_dialog.zip

未知大小

Go示例 #

realtime_dialog.zip

未知大小

Java示例 #

realtime_dialog.zip

未知大小

您可以通过以下步骤，快速体验与 Realtime 模型API实时对话的功能。

1. 下载realtime_dialog.zip文件到本地，依据操作系统类型对gordonklaus/portaudio依赖进行安装：
   1. macOS：

brew install portaudio

2. CentOS：

sudo yum install -y portaudio portaudio-devel

3. Debian/Ubuntu：

sudo apt-get install portaudio19-dev

2. 安装后在项目下运行：

go执行命令：go run . -v=0
python执行命令：python main.py

RealtimeAPI的交互流程目前只支持server_vad模式，该模式的交互流程如下：

1. 客户端发送StartSession事件初始化会话
2. 客户端可以随时通过TaskRequest事件将音频发送到服务端
3. 服务端在检测到用户说话的时候，会返回ASRInfo和ASRResponse事件，同时在检测到用户说话结束之后返回ASREnded事件
4. 服务端合成的音频通过TTSResponse事件将音频返回给客户端

4.1 文本输入 #

4.2 合成音频 #

当客户判定不使用模型生成闲聊内容时，系统允许客户多次上传文本执行音频合成，以满足多样化需求。整体交互示例如下所示：

4.3 外部RAG输入 #

4.4 联网Agent搜索源 #

提示：客户端在遇到服务端 5xx 错误时，可以统一触发重连逻辑。