# 一、接口说明

将短文本( ≤ 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=1512041814&appkey=xxxxxxxxxxx&sign=xxxxxxxxxx
1

# 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 发音人,需要在控制台 (opens new window)添加 参考发音人列表 需要在控制台添加
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="毫米汞柱">mmH</mute>或说取消 气压的测量单位是毫米汞柱

# 七、错误码

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

# 发音人列表

音库类型 发音人代码 发音人名称 发音人描述
精品音库 kiyo-plus Kiyo 可爱女生
jenny-plus Jenny 纯正美音
xiaowen-plus 小雯 女播音员
xiaofeng-plus 小峰 男播音员
xuanxuan-plus 萱萱 甜美女生
tiantian-plus 天天 天真男孩
tangtang-plus 糖糖 活泼女孩
普通音库 kiyo-base Kiyo 可爱女生
xiaowen-base 小雯 女播音员
xiaofeng-base 小峰 男播音员
xuanxuan-base 萱萱 甜美女生
tiantian-base 天天 天真男孩
tangtang-base 糖糖 活泼女孩
lingling-base 玲玲 台湾女生