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

1.1 产品约束

1. 客户端上传音频格式要求PCM（脉冲编码调制，未经压缩的的音频格式）、单声道、采样率16000、每个采样点用int16表示、字节序为小端序。
2. 服务端返回的是 OGG 封装的 Opus 音频，兼顾压缩效率与传输性能。
3. 若客户端在 StartSession事件中增加TTS配置，服务端可返回 PCM 格式的音频流（单声道、24000Hz 采样率、Float32 采样点、小端序）。具体请求参数如下所示：

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

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

1.2 最佳实践

1. 在客户端发送 FinishSession 事件后，系统将不再返回任何事件。但客户端仍可复用与火山语音网关之间的 WebSocket 连接。若需发起新的会话，客户端需重新从 StartSession 事件开始。（待定）
2. 在没有对话需求时候，可以发送FinishSession事件结束会话。如果不想复用websocket连接，可以继续发送FinishConnection事件，释放对应的websocket连接。
3. 推荐客户端在事件的 optional 字段中携带 event 和 session ID，以降低开发成本，并将事件处理的复杂性交由火山语音服务端负责。
4. 客户在集成端到端语音合成模型过程中，使用 ChatTTSText 进行音频合成请求的最佳实践方法，其中黄色部分需要客户重点关注：

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是具体负载的内容，依据不同的消息类型装载不同的内容

header二进制数据

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模型进行语音到语音的对话。需要发送客户端事件来启动操作，并监听服务器事件以采取对应的操作。

客户端事件

{}

{
    "dialog": {
        "bot_name": {{STRING}},
        "dialog_id": {{STRING}},
        "extra" : {
            "strict_audit": {{BOOLEAN}}
        }
    }
}

{}

{
    "content": {{STRING}}
}

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

备注：

• 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
}

• 最后一包

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

服务端事件

{}

{
    "error": {{STRING}}
}

{}

{
    "dialog_id": {{STRING}}
}

{}

{
    "error": {{STRING}}
}

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

{}

{}

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

{}

{
  "content": {{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

未知大小

您可以通过以下步骤，快速体验与 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 合成音频

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