跳转到主要内容
WSS
/
ws
/
v1
/
t2a_v2

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 流式
  • WebSocket 接口只支持返回 hex 格式 的音频数据。
  • 当最后一次收到服务端返回结果后超过 120 秒 没有发送新事件时,WebSocket 连接自动断开。
  • 音色模型名称:senseaudio-tts-1.5-260319

请求头 (Request Headers)

参数名必填说明示例
Authorization鉴权 Token。格式:Bearer SENSEAUDIO_API_KEYBearer sk-123456…
Content-Type内容类型。固定为 application/jsonapplication/json

通信流程

1. 客户端建立 WebSocket 连接

2. 服务端返回 connected_success 事件

3. 客户端发送 task_start 事件(包含音色、音频格式等配置)

4. 服务端返回 task_started 事件

5. 客户端发送 task_continue 事件(发送待合成文本)

6. 服务端返回音频数据(可多次发送 task_continue)

7. 客户端发送 task_finish 事件

8. 服务端返回 task_finished 事件并关闭连接

客户端事件

1. task_start - 开始任务

发送此事件正式开始合成任务。当服务端返回 task_started 事件时,标志着任务已成功开始。只有在接收到该事件后,才能向服务器发送 task_continuetask_finish 事件。 请求参数
参数名类型必填默认值说明
eventstring固定值:task_start
modelstring模型名称,示例值:senseaudio-tts-1.5-260319
voice_settingobject声音设置
voice_setting.voice_idstring主音色名称
voice_setting.speedfloat1.0语速,取值范围 [0.5, 2.0]
voice_setting.volfloat1.0音量,取值范围 [0.01, 10.0]
voice_setting.pitchint0音调,取值范围 [-12, 12],0 表示保持原始音调
voice_setting.latex_readbooleanfalse数学公式朗读,支持 LaTeX、MathML、Unicode 数学符号等格式。(会产生额外的性能损耗)
audio_settingobject音频格式设置
audio_setting.sample_rateint32000音频采样率,取值范围 [8000, 16000, 22050, 24000, 32000, 44100]
audio_setting.bitrateint128000音频码率,取值范围 [32000, 64000, 128000, 256000]
audio_setting.formatstringmp3输出格式:mp3、wav、pcm、flac
audio_setting.channelint2音频声道,1:单声道,2:双声道
请求示例
{
  "event": "task_start",
  "model": "senseaudio-tts-1.5-260319",
  "voice_setting": {
    "voice_id": "male_0004_a",
    "speed": 1,
    "vol": 1,
    "pitch": 0,
    "latex_read": false
  },
  "audio_setting": {
    "sample_rate": 32000,
    "bitrate": 128000,
    "format": "mp3",
    "channel": 1
  }
}
响应参数
参数名类型说明
session_idstring会话 ID
eventstring事件类型
trace_idstring链路追踪 ID
base_respobject请求状态信息
base_resp.status_codeinteger状态码
base_resp.status_msgstring状态详情
响应示例
{
  "session_id": "69c20e38c8761996a85d57881fe4d817",
  "event": "task_started",
  "trace_id": "69c20e38c8761996a85d57881fe4d817",
  "base_resp": { "status_code": 0, "status_msg": "success" }
}

2. task_continue - 任务继续

当收到服务端返回的 task_started 事件后,任务正式开始,可通过发送 task_continue 事件发送要合成的文本。支持顺序发送多个 task_continue 事件,实现分段文本合成。 请求参数
参数名类型必填说明示例
eventstring固定值:task_continue
textstring合成文本内容,支持中英文;支持 <break> 停顿符,详见下方停顿符说明
dictionaryarray多音字配置列表(模型必须为 senseaudio-tts-1.5-260319[{"original": "好干净","replacement": "[hao4]干净"}]

<break> 停顿符说明

<break> 用于在语音合成中插入停顿。
<break time=500>
  • time 单位为毫秒(ms)
  • 500 表示停顿 500 毫秒
  • 最小值为 100 毫秒,最大值无限制
示例:
你好<break time=500>欢迎使用我们的服务

dictionary (多音字纠正)

参数名类型必填描述默认值示例
originalstring原始文本。好干净
replacementstring多音字配置。[hao4]干净
请求示例
{
  "event": "task_continue",
  "text": "好干净",
  "dictionary": [
    { "original": "好干净", "replacement": "[hao4]干净" }
  ]
}
响应参数
参数名类型说明
session_idstring会话 ID
eventstring事件类型
trace_idstring链路追踪 ID
is_finalboolean当前 task_continue 语音合成任务是否结束
base_respobject请求状态信息
base_resp.status_codeinteger状态码
base_resp.status_msgstring状态详情
dataobject返回的合成数据对象(可能为 null)
data.audiostring合成后的音频数据(hex 编码)
data.statusinteger音频流状态:1 表示合成中,2 表示合成结束
extra_infoobject音频附加信息(流式返回时只有最后一个 chunk 会返回)
extra_info.audio_lengthinteger音频时长(毫秒)
extra_info.audio_sample_rateinteger音频采样率
extra_info.audio_sizeinteger音频文件大小(字节)
extra_info.bitrateinteger音频比特率
extra_info.audio_formatstring音频格式,取值范围 [mp3, pcm, flac, wav]
extra_info.audio_channelinteger音频声道数,1:单声道,2:双声道
extra_info.word_countinteger字数统计(按字素簇 grapheme cluster 统计,排除纯空白/标点/控制符)
extra_info.usage_charactersinteger字符数统计(按 Unicode 码点统计)
响应示例
{
  "session_id": "69c20e38c8761996a85d57881fe4d817",
  "event": "task_continued",
  "trace_id": "69c20e38c8761996a85d57881fe4d817",
  "is_final": false,
  "data": { "audio": "hex编码的音频数据...", "status": 1 },
  "base_resp": { "status_code": 0, "status_msg": "success" }
}

3. task_finish - 结束任务

服务端收到此事件后,会等待当前队列中所有合成任务完成后,关闭 WebSocket 连接并结束任务。 请求参数
参数名类型必填说明
eventstring固定值:task_finish
请求示例
{ "event": "task_finish" }
响应示例
{
  "session_id": "69c20e38c8761996a85d57881fe4d817",
  "event": "task_finished",
  "trace_id": "69c20e38c8761996a85d57881fe4d817",
  "base_resp": { "status_code": 0, "status_msg": "success" }
}

服务端事件

connected_success - 连接建立成功

初次请求接口时,表示 WebSocket 连接建立成功。
{
  "session_id": "xxxx",
  "event": "connected_success",
  "trace_id": "xxx",
  "base_resp": { "status_code": 0, "status_msg": "success" }
}

task_started - 任务已开始

标志任务已成功开始,客户端可以开始发送 task_continue 事件。
{
  "session_id": "xxxx",
  "event": "task_started",
  "trace_id": "xxxxx",
  "base_resp": { "status_code": 0, "status_msg": "success" }
}

task_finished - 任务已结束

标志任务已结束,WebSocket 连接即将关闭。
{
  "session_id": "xxxx",
  "event": "task_finished",
  "trace_id": "xxxx",
  "base_resp": { "status_code": 0, "status_msg": "success" }
}

task_failed - 任务失败

标志任务失败,base_resp.status_msg 中包含错误信息。
{
  "session_id": "xxxx",
  "event": "task_failed",
  "trace_id": "xxxxx",
  "base_resp": { "status_code": 1004, "status_msg": "具体错误信息" }
}

使用示例

依赖:npm install ws
const fs = require('fs')
const WebSocket = require('ws')

const WS_URL = 'wss://api.senseaudio.cn/ws/v1/t2a_v2'
const API_KEY = process.env.SENSEAUDIO_API_KEY
if (!API_KEY) throw new Error('Missing env: SENSEAUDIO_API_KEY')

const output = fs.createWriteStream('output.mp3')
const ws = new WebSocket(WS_URL, {
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
})

ws.on('open', () => console.log('WebSocket 连接已建立'))

ws.on('message', (data) => {
  const response = JSON.parse(data.toString())
  console.log('收到服务端事件:', response.event)

  if (response.event === 'connected_success') {
    ws.send(JSON.stringify({
      event: 'task_start',
      model: 'senseaudio-tts-1.5-260319',
      voice_setting: { voice_id: 'male_0004_a', speed: 1.0, vol: 1.0, pitch: 0, latex_read: false },
      audio_setting: { sample_rate: 32000, bitrate: 128000, format: 'mp3', channel: 1 },
    }))
    return
  }

  if (response.event === 'task_started') {
    ws.send(JSON.stringify({ event: 'task_continue', text: '道可道,非常道。名可名,非常名。无名天地之始,有名万物之母。' }))
    ws.send(JSON.stringify({ event: 'task_continue', text: '故常无欲,以观其妙;常有欲,以观其徼。' }))
    ws.send(JSON.stringify({ event: 'task_finish' }))
    return
  }

  if (response?.data?.audio) {
    output.write(Buffer.from(response.data.audio, 'hex'))
  }

  if (response.event === 'task_finished') { output.end(); ws.close() }
  if (response.event === 'task_failed') {
    console.error('任务失败:', response?.base_resp?.status_msg)
    output.end(); ws.close()
  }
})

ws.on('error', (err) => console.error('WebSocket 错误:', err))
ws.on('close', () => console.log('WebSocket 连接已关闭'))

技术规格

  • 模型名称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参数错误检查请求参数格式和取值范围

注意事项

  1. 音频数据格式:WebSocket 接口只支持返回 hex 编码的音频数据,需要在客户端将 hex 字符串转换为二进制数据;音频格式由 audio_setting.format 决定。
  2. 连接超时机制:最后一次收到服务端返回后 120 秒内无新事件发送时连接自动断开;建议在任务完成后主动发送 task_finish,长时间无操作时可发送心跳保持连接。
  3. 事件发送顺序:必须按照 task_start → task_continue → task_finish 顺序发送;只有在收到 task_started 后才能发送 task_continue;可以发送多个 task_continue 事件。

相关资源

语音合成 HTTP

标准 HTTP 合成接口参数详解。

语音合成 HTTP 流式

流式 HTTP 合成接口参数详解。

语音合成介绍

TTS 核心特性与音色生态。

音色列表

系统音色清单与 voice_id 规则。
Messages
bearerAuth
type:http

Bearer Token 鉴权,格式 Authorization: Bearer <SENSEAUDIO_API_KEY>

task_start
type:object

开始合成任务

task_continue
type:object

发送待合成文本

task_finish
type:object

结束合成任务

connected_success
type:object

连接建立成功

task_started
type:object

任务已开始

task_continued

音频分片返回

task_finished
type:object

任务已结束

task_failed
type:object

任务失败