Messages
语音合成
语音合成 WebSocket (TTS)
基于 WebSocket 的实时 TTS 合成协议参考
WSS
Documentation Index
Fetch the complete documentation index at: https://docs.senseaudio.cn/llms.txt
Use this file to discover all available pages before exploring further.
说明
基于 WebSocket 的实时文本到语音合成接口,支持增量式文本输入与流式音频输出,适用于实时对话、在线客服、边生成边播报等低延迟场景。单次连接支持多次合成任务,最大文本长度 10000 字符。- 接入地址:
wss://api.senseaudio.cn/ws/v1/t2a_v2 - 鉴权方式:Bearer Token,格式
Authorization: Bearer SENSEAUDIO_API_KEY - 消息格式:
application/json,音频仅返回 hex 编码字符串 - 计费单位:按合成字符数计费,详见 计费说明
- 音色入参:
voice_id必须为当前账号可用音色,参考 音色列表 - 标准 HTTP 合成:参考 语音合成 HTTP
- SSE 合成:参考 语音合成 HTTP 流式
请求头 (Request Headers)
| 参数名 | 必填 | 说明 | 示例 |
|---|---|---|---|
| Authorization | 是 | 鉴权 Token。格式:Bearer SENSEAUDIO_API_KEY | Bearer sk-123456… |
| Content-Type | 是 | 内容类型。固定为 application/json | application/json |
通信流程
客户端事件
1. task_start - 开始任务
发送此事件正式开始合成任务。当服务端返回 task_started 事件时,标志着任务已成功开始。只有在接收到该事件后,才能向服务器发送 task_continue 或 task_finish 事件。 请求参数| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| event | string | 是 | 无 | 固定值:task_start |
| model | string | 是 | 无 | 模型名称,示例值:senseaudio-tts-1.5-260319 |
| voice_setting | object | 是 | 无 | 声音设置 |
| voice_setting.voice_id | string | 是 | 无 | 主音色名称 |
| voice_setting.speed | float | 否 | 1.0 | 语速,取值范围 [0.5, 2.0] |
| voice_setting.vol | float | 否 | 1.0 | 音量,取值范围 [0.01, 10.0] |
| voice_setting.pitch | int | 否 | 0 | 音调,取值范围 [-12, 12],0 表示保持原始音调 |
| voice_setting.latex_read | boolean | 否 | false | 数学公式朗读,支持 LaTeX、MathML、Unicode 数学符号等格式。(会产生额外的性能损耗) |
| audio_setting | object | 否 | 无 | 音频格式设置 |
| audio_setting.sample_rate | int | 否 | 32000 | 音频采样率,取值范围 [8000, 16000, 22050, 24000, 32000, 44100] |
| audio_setting.bitrate | int | 否 | 128000 | 音频码率,取值范围 [32000, 64000, 128000, 256000] |
| audio_setting.format | string | 否 | mp3 | 输出格式:mp3、wav、pcm、flac |
| audio_setting.channel | int | 否 | 2 | 音频声道,1:单声道,2:双声道 |
| 参数名 | 类型 | 说明 |
|---|---|---|
| session_id | string | 会话 ID |
| event | string | 事件类型 |
| trace_id | string | 链路追踪 ID |
| base_resp | object | 请求状态信息 |
| base_resp.status_code | integer | 状态码 |
| base_resp.status_msg | string | 状态详情 |
2. task_continue - 任务继续
当收到服务端返回的 task_started 事件后,任务正式开始,可通过发送 task_continue 事件发送要合成的文本。支持顺序发送多个 task_continue 事件,实现分段文本合成。 请求参数| 参数名 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
| event | string | 是 | 固定值:task_continue | |
| text | string | 是 | 合成文本内容,支持中英文;支持 <break> 停顿符,详见下方停顿符说明 | |
| dictionary | array | 否 | 多音字配置列表(模型必须为 senseaudio-tts-1.5-260319) | [{"original": "好干净","replacement": "[hao4]干净"}] |
<break> 停顿符说明
<break> 用于在语音合成中插入停顿。
- time 单位为毫秒(ms)
- 500 表示停顿 500 毫秒
- 最小值为 100 毫秒,最大值无限制
dictionary (多音字纠正)
| 参数名 | 类型 | 必填 | 描述 | 默认值 | 示例 |
|---|---|---|---|---|---|
| original | string | 是 | 原始文本。 | 无 | 好干净 |
| replacement | string | 是 | 多音字配置。 | 无 | [hao4]干净 |
| 参数名 | 类型 | 说明 |
|---|---|---|
| session_id | string | 会话 ID |
| event | string | 事件类型 |
| trace_id | string | 链路追踪 ID |
| is_final | boolean | 当前 task_continue 语音合成任务是否结束 |
| base_resp | object | 请求状态信息 |
| base_resp.status_code | integer | 状态码 |
| base_resp.status_msg | string | 状态详情 |
| data | object | 返回的合成数据对象(可能为 null) |
| data.audio | string | 合成后的音频数据(hex 编码) |
| data.status | integer | 音频流状态:1 表示合成中,2 表示合成结束 |
| extra_info | object | 音频附加信息(流式返回时只有最后一个 chunk 会返回) |
| extra_info.audio_length | integer | 音频时长(毫秒) |
| extra_info.audio_sample_rate | integer | 音频采样率 |
| extra_info.audio_size | integer | 音频文件大小(字节) |
| extra_info.bitrate | integer | 音频比特率 |
| extra_info.audio_format | string | 音频格式,取值范围 [mp3, pcm, flac, wav] |
| extra_info.audio_channel | integer | 音频声道数,1:单声道,2:双声道 |
| extra_info.word_count | integer | 字数统计(按字素簇 grapheme cluster 统计,排除纯空白/标点/控制符) |
| extra_info.usage_characters | integer | 字符数统计(按 Unicode 码点统计) |
3. task_finish - 结束任务
服务端收到此事件后,会等待当前队列中所有合成任务完成后,关闭 WebSocket 连接并结束任务。 请求参数| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| event | string | 是 | 固定值:task_finish |
服务端事件
connected_success - 连接建立成功
初次请求接口时,表示 WebSocket 连接建立成功。task_started - 任务已开始
标志任务已成功开始,客户端可以开始发送 task_continue 事件。task_finished - 任务已结束
标志任务已结束,WebSocket 连接即将关闭。task_failed - 任务失败
标志任务失败,base_resp.status_msg 中包含错误信息。
使用示例
- Node.js
- Python
- Go
- Java
依赖:npm install ws
技术规格
- 模型名称:senseaudio-tts-1.5-260319
- 最大文本长度:10000 字符
- 连接超时:最后一次收到服务端返回后 120 秒无新事件时自动断开
音频参数范围
| 参数 | 取值范围 | 默认值 | 说明 |
|---|---|---|---|
| 语速 | [0.5, 2.0] | 1.0 | 数值越大语速越快 |
| 音量 | [0.01, 10.0] | 1.0 | 数值越大音量越大 |
| 音调 | [-12, 12] | 0 | 正值提高,负值降低 |
| 采样率 | 8000, 16000, 22050, 24000, 32000, 44100 (Hz) | 32000 | 推荐 32000 |
| 码率 | 32000, 64000, 128000, 256000 (bps) | 128000 | 仅 MP3 格式 |
| 声道 | 1 (单声道), 2 (双声道) | 2 | - |
支持的音频格式
- MP3:推荐,压缩率高,兼容性好。
- WAV:无损音质,文件较大。
- PCM:原始音频数据。
- FLAC:无损压缩。
错误码说明
| 状态码 | 说明 | 解决方案 |
|---|---|---|
| 0 | 成功 | - |
| 1001 | 参数错误 | 检查请求参数格式和取值范围 |
注意事项
- 音频数据格式:WebSocket 接口只支持返回 hex 编码的音频数据,需要在客户端将 hex 字符串转换为二进制数据;音频格式由
audio_setting.format决定。 - 连接超时机制:最后一次收到服务端返回后 120 秒内无新事件发送时连接自动断开;建议在任务完成后主动发送
task_finish,长时间无操作时可发送心跳保持连接。 - 事件发送顺序:必须按照
task_start → task_continue → task_finish顺序发送;只有在收到task_started后才能发送task_continue;可以发送多个task_continue事件。
相关资源
语音合成 HTTP
标准 HTTP 合成接口参数详解。
语音合成 HTTP 流式
流式 HTTP 合成接口参数详解。
语音合成介绍
TTS 核心特性与音色生态。
音色列表
系统音色清单与
voice_id 规则。Messages