文字合成语音-云知声短文本语音合成

一、接口说明
二、接口Demo
三、接口要求
四、IP白名单
五、接口调用流程
六、TTS标签
七、错误码
八、发音人列表

# 一、接口说明

将短文本（ ≤ 500 字符）转换成自然流畅的语音，可流式播放，支持多种音色，并提供调节音量、语速、音高、亮度等功能。适用于智能客服、语音交互、导航播报等场景。

# 二、接口Demo

Java示例demo (opens new window)
python3示例demo (opens new window)
js示例demo (opens new window)

# 三、接口要求

集成短文本语音合成API时，需按照以下要求：

内容	说明
请求协议	ws[s]（为提高安全性，强烈推荐wss）
请求地址	ws[s]: //ws-stts.hivoice.cn/v1/tts
接口鉴权	签名机制，详情请参照下方接口鉴权
字符编码	UTF-8
响应格式	统一采用JSON格式
开发语言	任意，只要可以向服务发起Websocket请求的均可
操作系统	任意
音频属性	采样率24KHz或16KHz或8KHz、位长16bit、单声道
音频格式	pcm,mp3
文本长度	单次调用长度需小于500个字符
发音人	中英文男女声多风格，可以在这里 (opens new window)在线体验发音人效果

# 四、IP白名单

默认关闭IP白名单，即该服务不限制调用IP。在调用该业务接口时

若关闭IP白名单，接口认为IP不限，不会校验IP。
若打开IP白名单，则服务端会检查调用方IP是否在开放平台配置的IP白名单中，对于没有配置到白名单中的IP发来的请求，服务端会拒绝服务。
若打开IP白名单，同时没有设置任何IP，接口会认为此时没有设置白名单，所以打开IP白名单时，请务必设置IP，否则无法生效。

IP白名单规则

登录云知声AI开放平台控制台 (opens new window)
选择应用的查看详情
IP白名单处编辑，保存后五分钟左右生效。
不同appkey的不同服务都需要分别设置IP白名单。
IP白名单需设置为外网IP，请勿设置局域网IP。

# 五、接口调用流程

通过接口密钥基于SHA256计算签名，向服务器端发送Websocket协议握手请求。详见接口鉴权。
握手成功后，客户端通过Websocket连接同时上传和接收数据。详见下方接口数据传输与接收。
接收到服务器端的结果end=true标识后断开Websocket连接。

注： Websocket使用注意事项如下

服务端支持的websocket-version 为13，请确保客户端使用的框架支持该版本。
服务端返回的所有的帧类型均为TextMessage，对应于原生websocket的协议帧中opcode=1，请确保客户端解析到的帧类型一定为该类型，如果不是，请尝试升级客户端框架版本，或者更换技术框架。
如果出现分帧问题，即一个json数据包分多帧返回给了客户端，导致客户端解析json失败。出现这种问题大部分情况是客户端的框架对websocket协议解析存在问题，如果出现请先尝试升级框架版本，或者更换技术框架。
客户端会话结束后如果需要关闭连接，尽量保证传给服务端的错误码为websocket错误码1000（如果客户端框架没有提供关闭时传错误码的接口。则无需关注本条）。

# 1、接口鉴权

在握手阶段，请求方需要对请求进行签名，服务端通过签名来校验请求的合法性。
请求示例

ws[s]://ws-stts.hivoice.cn/v1/tts?time=1585047674022&appkey=xxxxxxxxxxx&sign=xxxxxxxxxx

# 1.1、鉴权方法

参数	描述	示例	备注
appkey	用户的appkey	***	必需
time	访问时间戳,Unix时间戳（毫秒数）	1585047674022	必需
sign	签名	***	必需

A）将上述参数按照appkey、time、secret secret查询 (opens new window) 顺序拼接字符串；
B）将A形成字符串获取SHA256摘要，形成一个64位的十六进制（字母大写）字符串，即为本次请求sign（签名）的值

# 1.2、鉴权示例代码

/**
* 热词签名获取方法
* @param appkey
* @param timestamp
* @param secret
* @return
*/
public String getSign(String appkey, String timestamp, String secret) {
    String originalStr = appkey + timestamp + secret;
    StringBuilder sign = new StringBuilder();
    try {
        MessageDigest md = MessageDigest.getInstance("SHA-256");
        byte[] bytes = md.digest(originalStr.getBytes(StandardCharsets.UTF_8));
        for (int i = 0; i < bytes.length; i++) {
            String hex = Integer.toHexString(bytes[i] & 0xFF);
            if (hex.length() == 1) {
                sign.append("0");
            }
            sign.append(hex.toUpperCase());
        }
    } catch (Exception unused) {
    }
    return sign.toString();
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

# 1.3、鉴权结果

如果握手成功，会返回HTTP 101状态码，表示协议升级成功；
如果握手失败，则根据不同错误类型返回不同HTTP Code状态码，同时携带错误描述信息，
详细错误说明如下：

HTTP Code	说明	解决方法
401	签名校验失败	签名验证失败，可能原因有多种。 1. 检查appkey,signature 是否正确 2.检查计算签名的参数appkey，timestamp，secret是否按照协议要求拼接。
403	时钟偏移校验失败	检查服务器时间是否标准，相差5分钟以上会报此错误

# 2、开始合成

通过websocket文本传输，json格式数据

# 2.1、参数说明

参数名	类型	必传	描述	可选值	默认
format	string	否	音频格式	pcm,mp3	pcm
sample	string	否	采样率（单位Hz）	8000,16000,24000	16000
vcn	string	是	发音人	参考发音人列表
speed	int	否	语速	0~100	50
volume	int	否	音量	0~100	50
pitch	int	否	音高	0~100	50
bright	int	否	亮度	50~100	50
text	string	是	需要合成的文本，最大500字符，超过500个字符会被截断
user_id	string	否	用户标识

# 2.2、请求参数示例

{
	"vcn": "xiaowen-base",
	"volume": 50,
	"user_id": "unisound-java-demo",
	"format": "pcm",
	"bright": 50,
	"pitch": 50,
	"smt": 0,
	"text": "云知声专注于物联网人工智能服务，拥有完全自主知识产权，是世界领先的智能语音识别AI技术企业之一。公司成立于2012年6月29日，总部位于北京，在上海、深圳、厦门、合肥均设有分公司。",
	"sample": "16000",
	"emt": 0,
	"speed": 50
}

1
2
3
4
5
6
7
8
9
10
11
12
13

# 3、接收语音

接收语音数据是通过websocket的onMessage(byte)方法，
websocket返回的二进制数据即为合成的语音数据。

# 4、合成结束

当服务端合成结束或出错时会返回文本消息。

接收文本结果是通过onMessage(String)方法，文本结果描述如下：

参数	类型	描述	是否为空
code	int	处理结果	NO
msg	string	结果说明	NO
sid	string	识别的唯一id	NO
end	boolean	请求是否结束	NO

返回结果示例

{
	"code": 0,
	"end": true,
	"msg": "success",
	"sid": "29d5e5f3f2be4fac97ab97be6f8efc04"
}

1
2
3
4
5
6

# 六、TTS标签

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

# 七、错误码

错误码	说明	解决方法
0	正确
20301	参数错误	客户端检查参数是否正确
20302	发音人不可用	到控制台查看可用发音人
20303	服务内部错误	建议重试，或者提工单，工单详情请提供sid
20304	并发超过限制	减小并发或者购买并发套餐
20305	套餐次数使用完	购买次数套餐
20306	appkey不存在	检查appkey是否合法
20307	客户端ip不在白名单中	检查是否开启白名单，同时检查客户端出口ip是否在ip白名单中

# 八、发音人列表

音库类型	发音人名称	发音人风格	发音人代码	发音人描述
大模型	晨宇	默认	chenyu-llm	清朗明快
	johnny	默认	johnny-llm	纯正美音
	晓迪	默认	xiaodi-llm	温柔舒缓
	jane	默认	jane-llm	英语女声
精品音库	橙橙	默认	chengcheng-neutral-plus	知性大方
		开心	chengcheng-happy-plus
		生气	chengcheng-angry-plus
		厌恶	chengcheng-disgust-plus
		害怕	chengcheng-fear-plus
		难过	chengcheng-sad-plus
		吃惊	chengcheng-amazed-plus
	莎莎	默认	shasha-neutral-plus	亲和自然
		开心	shasha-happy-plus
		生气	shasha-angry-plus
		厌恶	shasha-disgust-plus
		害怕	shasha-fear-plus
		难过	shasha-sad-plus
		惊喜	shasha-surprise-plus
	晓迪	默认	xiaodi-plus	温柔舒缓
	晓迪	温暖	xiaodi-warm-plus	温柔舒缓
	Kiyo	元气	kiyo-plus	可爱女生
	Kiyo	职业	suren-plus	可爱女生
	萱萱	默认	xuanxuan-plus	甜美女生
	萱萱	端庄	xuanxuan-dignified-plus	甜美女生
	晓琴	默认	xiaoqin-plus	亲切温和
	Jenny	默认	jenny-plus	纯正美音
	小峰	默认	xiaofeng-plus	男播音员
	小峰	庄重	xiaofeng-solemn-plus	男播音员
	小雯	默认	xiaowen-plus	女播音员
	小雯	庄重	xiaowen-solemn-plus	女播音员
	天天	默认	tiantian-plus	天真男孩
	糖糖	默认	tangtang-plus	活泼女孩
	珍妮	默认	zhenni-plus	异域风情
	玲玲	默认	lingling-plus	台湾女生
	晓珂	默认	xiaoke-plus	漂亮御姐
	宁宁	默认	ningning-plus	粤语女声
	冰冰	默认	bingbing-duihua-plus	明亮利落
		客服	bingbing-kefu-plus
		消极	bingbing-neg-plus
		积极	bingbing-pos-plus
	贝儿	默认	beier-plus	元气少女
	惠惠	默认	huihui-normal-plus	成熟大方
		中立	huihui-neutral-plus
		生气	huihui-angry-plus
		害怕	huihui-fear-plus
		开心	huihui-happy-plus
		难过	huihui-sad-plus
		惊喜	huihui-surprise-plus
		讽刺	huihui-sarcastic-plus
		可疑	huihui-suspicious-plus
	晨阳	默认	chenyang-normal-plus	真实自然
		中立	chenyang-neutral-plus
		生气	chenyang-angry-plus
		害怕	chenyang-fear-plus
		开心	chenyang-happy-plus
		难过	chenyang-sad-plus
		惊喜	chenyang-surprise-plus
		讽刺	chenyang-sarcastic-plus
		可疑	chenyang-suspicious-plus
	小颖	默认	xiaoying-plus	亲和自然
	雅琳	默认	yalin-plus	成熟温和
	小亮	默认	xiaoliang-plus	清朗明快
	明宇	默认	mingyu-plus	稳重浑厚
	盈盈	默认	yingying-plus	四川女声
	Tiffany	默认	tiffany-plus	纯正美音
	Johnny	默认	johnny-plus	纯正美音
	飞行少年	默认	feixingshaonian-plus	Rapper
	嘉仪	默认	jiayi-plus	粤语女声
云婧	默认	yunjing-plus	女声
知轩	默认	zhixuan-plus	男声
云悠	默认	yunyou-plus	女声
姗姗	默认	shanshan-plus	四川女声
知翔	默认	zhixiang-plus	男声
绵儿	默认	mianer-plus	四川女声
zoey	默认	zoey-plus	英语女声
bill	默认	bill-plus	英语男声
jane	默认	jane-plus	英语女声
普通音库	Kiyo	默认	kiyo-base	可爱女生
	小雯	默认	xiaowen-base	女播音员
	小峰	默认	xiaofeng-base	男播音员
	萱萱	默认	xuanxuan-base	甜美女生
	天天	默认	tiantian-base	天真男孩
	糖糖	默认	tangtang-base	活泼女孩
	玲玲	默认	lingling-base	台湾女生

← WebAPI文档 iOS SDK文档 →