同步语音合成

基于 WebSocket 协议提供文本到语音的同步合成能力，支持流式返回音频。

WSS/v1/ws/tts

协议	WebSocket（文本 JSON + 二进制音频）
网关路径	/v1/ws/tts
响应	二进制音频帧 + 文本 JSON 控制帧

授权

Authorizationstringheader必填

HTTP: Bearer Auth

Security Scheme Type: http
HTTP Authorization Scheme: Bearer API_key，用于验证账户信息，可在按量计费&资源包>API Key 管理中查看。

连接

URL

建立 WebSocket 连接时使用以下地址：

wss://{gateway-host}/v1/ws/tts?model={model_id}

Query 参数

model必填

模型编码，可选值：u2-tts。

握手 Header（客户端 → 网关）

Authorization必填

Bearer {api_key}

Connection必填

Upgrade

Upgrade必填

websocket

握手失败（未建立 WebSocket）

返回 HTTP 状态码 401 / 429 等

会话流程

建立 WebSocket 连接
发送文本帧 start，在其中携带待合成全文 text，并配置 voice_setting / audio_setting
按序接收二进制音频帧
接收文本控制帧（end=true），本轮合成结束

客户端消息

文本帧：start

每条连接仅可发送一次 start。根对象为扁平 JSON。

typestring必填

请求阶段，固定为 start

sidstring

客户端会话 ID，可选；响应中原样回传。不传则由服务端生成

textstring必填

待合成文本，长度限制小于 500 字符

voice_settingobject必填

音色基础设置

voice_setting.voice_idstring必填

音色 ID，可通过查询可用音色 API 获取

voice_setting.speedinteger

语速范围 [0, 100]，默认 50。

具体支持详情参见音色参数支持说明。

voice_setting.volumeinteger

音量范围 [0, 100]，默认 50。

具体支持详情参见音色参数支持说明。

voice_setting.pitchinteger

音高范围 [0, 100]，默认 50。

具体支持详情参见音色参数支持说明。

voice_setting.brightinteger

亮度范围 [0, 100]，默认 50。

具体支持详情参见音色参数支持说明。

voice_setting.emotionstring

发音情绪，可选值：happy, angry, depressed, whisper, loudly, neutral，分别对应 6 种情绪：高兴，愤怒，沮丧，低语，大声，中性。目前仅 cn_male_chenyu 发音人，且语种为中文、方言为默认时支持。

voice_setting.languagestring

发音语种，可选值：zh, ja, ko, th, vi, id, ms, my, lo, km, tl, en。默认 zh。

不同音色支持的语种如下：

`cn_female_shasha`：`zh`（中文）、`ja`（日语）、`ko`（韩语）、`th`（泰语）、`vi`（越南语）、`id`（印尼语）、`km`（柬埔寨语）
`cn_female_jiajia`：`zh`（中文）、`id`（印尼语）、`ms`（马来语）、`my`（缅甸语）、`lo`（老挝语）
`cn_male_chenyu`：`zh`（中文）、`tl`（菲律宾语）
`en_male_johnny`、`en_female_jane`：`en`（英语）
其余系统音色：`zh`（中文）

voice_setting.dialectstring

发音方言，可选值：default, yueyu, sichuan。默认 default。

目前仅 `cn_male_chenyu` 音色支持以下方言：

`yueyu`（粤语）
`sichuan`（四川话）

audio_settingobject

音频输出设置

audio_setting.audio_sample_rateinteger

采样率，枚举 [8000, 16000, 24000, 32000]，默认 32000

audio_setting.formatstring

输出格式，枚举 [mp3, pcm]，默认 mp3

audio_setting.channelinteger

声道数，枚举 [1]，默认 1

pronunciation_dictobject

自定义发音规则

pronunciation_dict.tonestring[ ]

发音/注音替换规则，示例：["水泊梁山/水泊<py>po1</py>梁山"]。

具体标签说明与支持详情参见自定义发音规则说明。

服务端响应

二进制帧：音频

类型: WebSocket Binary
内容: 按 audio_setting.format 编码的音频分片（非 Base64），按序拼接即为完整音频

文本控制帧

sidstring

与 start.sid 一致（若客户端传入）

base_respobject必填

本次请求的状态码及其详情

base_resp.status_codeinteger必填

状态码，0 表示成功

base_resp.status_msgstring必填

状态详情，成功为 success

endboolean必填

true 表示本轮合成结束

错误码

业务错误码	业务描述信息	解决方法
100001	参数错误（model/voice_id/文本超限/流式不支持等，公共码）	检查 model / voice_id / 文本长度等参数
204001	文本含敏感词	修改待合成文本后重试
204008	连接空闲超时（默认 30s 无活动）	请及时发送消息或重建连接
204011	未 start 或重复 start	每条连接仅发送一次 start
204099	服务内部错误	请稍后重试；持续失败请联系客服并提供 sid

Connect & Session

# Connect (wscat example)
wscat -c "wss://maas-api.unisound.com/v1/ws/tts?model=u2-tts" \
  -H "Authorization: Bearer <api_key>"

# Text frame: start
{
  "type": "start",
  "text": "水泊梁山的故事家喻户晓",
  "voice_setting": {
    "voice_id": "cn_male_chenyu",
    "volume": 50,
    "pitch": 50,
    "bright": 50,
    "language": "zh"
  },
  "pronunciation_dict": {
    "tone": ["水泊梁山/水泊<py>po1</py>梁山"]
  },
  "audio_setting": {
    "audio_sample_rate": 32000,
    "format": "mp3"
  }
}

# Binary frames: audio chunks (not Base64)

Control Frame

{
  "sid": "acd2231663054adcaaa13bd2e90729ee",
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  },
  "end": true
}

音色参数支持说明

不同音色在指定语种、方言下，对 speed、volume、pitch、bright 的支持情况如下。

音色 ID (Voice ID)	语种 (language)	方言 (dialect)	speed	volume	pitch	bright
cn_female_xiaodi_warm	zh	默认	✓	✓	✓	✓
cn_male_chenyu	zh	默认	✗	✓	✓	✓
cn_male_chenyu	zh	yueyu	✓	✓	✓	✓
cn_male_chenyu	zh	sichuan	✓	✓	✓	✓
cn_male_chenyu	tl	默认	✗	✗	✗	✗
en_male_johnny	en	默认	✓	✓	✓	✓
en_female_jane	en	默认	✓	✓	✓	✓
cn_male_chenyu_robot	zh	默认	✗	✓	✓	✓
cn_male_chenyu_elderly	zh	默认	✗	✓	✓	✓
cn_male_chenyu_steady	zh	默认	✗	✓	✓	✓
cn_male_chenyu_fluent	zh	默认	✗	✓	✓	✓
cn_female_shasha	zh, ja, ko, th, vi, id	默认	✗	✓	✓	✓
cn_female_shasha	km	默认	✗	✗	✗	✗
cn_female_jiajia	zh	默认	✗	✓	✓	✓
cn_female_jiajia	id, ms, my, lo	默认	✗	✗	✗	✗
cn_female_ruolin	zh	默认	✗	✓	✓	✓

自定义发音规则说明

可通过以下标签控制读音与断句。不同音色支持的标签不同，详见下方支持情况。

类别	标签	标注作用	文本标注	播报效果
数字类	<value>	使数字串按照数值的方式发音	这是第<value>110</value>会议室	这是第一百一十会议室
	<code>	使数字串按照编码的方式发音（“1”读作“一”）	这是第<code>110</code>会议室	这是一一零会议室
	<tel>	使数字串按照电话号码的方式发音（“1”读作“幺”）	会议室分机号为<tel>110</tel>	会议室分机号为幺幺零
注音类	<py>	使引擎按照指定的读音播报汉字	搜索结果为<py>wei2</py>空<py>kong1</py>	搜索结果为(wei2)空(kong1)
注音类	<pname>	使引擎正确播报姓名中的多音字姓氏	播放<pname>单田芳</pname>的评书	播放单(shan4)田芳的评书
断句类	<word>	按标注进行分词，用于解决分词错误。例如区分（乒乓球）（拍卖）（完了）与（乒乓）（球拍）（卖完了）	<word>乒乓</word><word>球拍</word><word>卖完了</word>	(乒乓)(球拍)(卖完了)
断句类	<phrase>	按标注进行断句（停顿长于 word），用于解决断句错误。例如区分（爸爸亲了我妈妈）（也亲了我）与（爸爸亲了我）（妈妈也亲了我）	<phrase>爸爸亲了我</phrase><phrase>妈妈也亲了我</phrase>	(爸爸亲了我) (妈妈也亲了我)
英文类	<letter>	将标注的英文按字母逐个播报	世界卫生组织的英文缩写<letter>WHO</letter>	世界卫生组织的英文缩写是(W)(H)(O)
其他	<mute>	在句中手动增加指定时长的停顿（单位：毫秒）	请您再说一遍<mute>300</mute>或说取消	请您再说一遍(停顿300ms)或说取消
其他	<sub>	使用 alias 属性中的内容替换标注文本进行播报	气压的测量单位是<sub alias="毫米汞柱">mmHg</sub>	气压的测量单位是毫米汞柱

标签支持情况

音色 ID (Voice ID)	语种 (language)	方言 (dialect)	支持标签
cn_female_xiaodi_warm	zh	默认	全部支持
cn_male_chenyu	zh	默认	部分支持（value、code、tel、py、letter、sub、word）
cn_male_chenyu	zh	yueyu	全部支持
cn_male_chenyu	zh	sichuan	全部支持
cn_male_chenyu	tl	默认	不支持
en_male_johnny	en	默认	全部支持
en_female_jane	en	默认	全部支持
cn_male_chenyu_robot	zh	默认	部分支持（value、code、tel、py、letter、sub、word）
cn_male_chenyu_elderly	zh	默认	部分支持（value、code、tel、py、letter、sub、word）
cn_male_chenyu_steady	zh	默认	部分支持（value、code、tel、py、letter、sub、word）
cn_male_chenyu_fluent	zh	默认	部分支持（value、code、tel、py、letter、sub、word）
cn_female_shasha	zh, ja, ko, th, vi, id	默认	部分支持（value、code、tel、py、letter、sub、word）
cn_female_shasha	km	默认	不支持
cn_female_jiajia	zh	默认	部分支持（value、code、tel、py、letter、sub、word）
cn_female_jiajia	id, ms, my, lo	默认	不支持
cn_female_ruolin	zh	默认	部分支持（value、code、tel、py、letter、sub、word）