文字合成语音|AI文字转语音-云知声长文本语音合成

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

# 一、接口说明

将长文本（ ≤ 5 万字符）转换成自然流畅的语音，提供更多音色、不同情感的发音人，支持输出PCM、WAV、MP3编码格式数据，适用于文学阅读、新闻播报、自媒体配音等场景。合成音可供下载使用。

# 二、接口Demo

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

# 三、接口要求

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

内容	说明
请求协议	http[s] （为提高安全性，强烈推荐https）
请求方式	POST
请求地址	http[s]: //ltts.hivoice.cn
接口鉴权	签名机制，详情请参照下方接口鉴权
字符编码	UTF-8
响应格式	统一采用JSON格式
开发语言	任意，只要可以向服务发起发起HTTP请求的均可
操作系统	任意
音频属性	采样率24KHz或16KHz或8KHz、位长16bit，单声道
音频格式	pcm,mp3,wav
文本长度	单次调用长度需小于5万个字符
发音人	中英文男女声多风格，可以在这里 (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。

# 五、接口调用流程

长文本语音合成API包括以下接口：开始合成、查询合成结果。客户端向服务端发送携带文本内容的HTTPS POST方法的请求，服务端返回对应的处理。此后客户端有两种处理方式：

主动轮询合成状态，直至合成完成。
等待服务端全部完成语音合成后主动回调用户设置的回调地址，此时用户端程序可以继续进行后续处理。

avatar

# 1、接口鉴权

开始合成、查询合成结果接口都需要进行鉴权

# 1.1、鉴权方法

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

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

# 2、开始合成

请求体是请求参数组成的JSON格式字符串，因此在POST请求头部中的Content-Type必须设置为application/json。

协议	URL	方法
HTTP/HTTPS	http://ltts.hivoice.cn/start	POST

# 2.1、参数说明

参数名	类型	必传	描述	可选值	默认值
text	string	是	需要合成的文本，文本长度最大支持5万字符
vcn	string	是	发音人，需要在控制台 (opens new window)添加	参考发音人列表
format	string	否	音频格式	pcm,mp3	pcm
sample	string	否	采样率	8000,16000,24000	16000
speed	int	否	语速	0~100	50
volume	int	否	音量	0~100	50
pitch	int	否	音高	0~100	50
bright	int	否	亮度	50~100	50
user_id	string	否	用户标识
enable_phoneme	Boolean	否	是否返回音素信息注意：只有vcn为精品音库时，该字段生效	true false	false

# 2.2、请求参数示例

{
	"appkey": "xxxxxxxx",
	"format": "wav",
	"sign": "xxxxxxxx",
	"text": "云知声专注于物联网人工智能服务，是一家拥有完全自主知识产权、世界顶尖智能语音技术的人工智能企业。",
	"time": "1601276121343",
	"user_id": "unisound-long-text-demo",
	"vcn": "kiyo-base"
}

1
2
3
4
5
6
7
8
9

# 2.3、响应结果

参数名	类型	描述	可能为空
error_code	string	返回码	否
message	string	返回码信息	否
task_id	string	任务ID	是

# 2.4、响应结果示例

{
	"task_id": "85d6f85f56814857ac477ff61cc013ed",
	"error_code": 0,
	"message": "OK"
}

1
2
3
4
5

# 3、查询合成结果

此接口需要调用方轮训请求，直到task_status=done标识合成完毕

协议	URL	方法
HTTP/HTTPS	http://ltts.hivoice.cn/progress	POST

# 3.1、参数说明

参数名	类型	是否必填	描述
task_id	String	是	开始合成接口返回的tast_id

# 3.2、请求参数示例

{
    "appkey": "XXX",
    "time": "1545016319978",
    "sign": "XXX",
    "task_id": "68753A444D6F12269C600050E4C00067"
}

1
2
3
4
5
6

# 3.3、响应结果

参数名	类型	描述	可能为空
error_code	string	返回码	否
message	string	返回码信息	否
task_id	string	任务ID	否
task_status	任务状态：排队中：waiting 合成中：running 合成结束：done	任务ID	否
audio_address	string	合成完成的音频地址	是

# 3.4、响应结果示例

{
    "error_code": 0,
    "message": "OK",
    "task_id": "68753A444D6F12269C600050E4C00067",
    "task_status": "done",
    "audio_address": "https://XXX",
}

1
2
3
4
5
6
7

# 4、音频下载

GET方式访问合成结果中audio_address的url下载音频

WARNING

注意：音频下载地址3天有效，不支持重复下载 (使用浏览器打开可能触发多次访问，导致无法播放)

# 六、时间戳功能

长文本时间戳功能，可支持输出句子级别时间戳和音素级别时间戳，一般应用于视频中的音频与字幕时间对齐，虚拟人形象口型对齐场景。输出每次传入文本中各单句（在句号，逗号，问号，感叹号，分号位置切分）在音频中的时间位置，即句级别时间戳。时间信息可用于视频配音字幕或有声书播报文字高亮等场景，非此类场景的可以不用开启时间戳参数。

# 1、开始合成

时间戳功能是在通用长文本合成的基础上开启enable_phoneme参数即可。

# 1.1、请求参数示例

{
	"appkey": "xxxxxx",
	"format": "wav",
	"sign": "xxxxxx",
	"text": "云知声专注于物联网人工智能服务，是一家拥有完全自主知识产权、世界顶尖智能语音技术的人工智能企业。",
	"time": "1601276121343",
	"user_id": "unisound-long-text-demo",
	"vcn": "kiyo-plus", //只有精品音库支持时间戳功能
	"enable_phoneme":"true"
}

1
2
3
4
5
6
7
8
9
10

# 1.2、响应结果

参数名	类型	描述	可能为空
error_code	string	返回码	否
message	string	返回码信息	否
task_id	string	任务ID	是

# 1.3、响应结果示例

{
	"task_id": "85d6f85f56814857ac477ff61cc013ed",
	"error_code": 0,
	"message": "OK"
}

1
2
3
4
5

# 2、查询合成结果

此接口需要调用方轮训请求，直到task_status=done标识合成完毕

协议	URL	方法
HTTP/HTTPS	http://ltts.hivoice.cn/progress	POST

# 2.1、参数说明

参数名	类型	是否必填	描述
task_id	String	是	开始合成接口返回的tast_id

# 2.2、请求参数示例

{
    "appkey": "XXX",
    "time": "1545016319978",
    "sign": "XXX",
    "task_id": "68753A444D6F12269C600050E4C00067"
}

1
2
3
4
5
6

# 2.3、响应结果

参数名	类型	描述	可能为空
error_code	string	返回码	否
message	string	返回码信息	否
task_id	string	任务ID	否
task_status	任务状态：排队中：waiting 合成中：running 合成结束：done	任务ID	否
audio_address	string	合成完成的音频地址	是
phoneme_address	string	音素信息文件地址。当enable_phoneme为true时，文件内容为音素信息结构数组。	是

# 2.4、响应结果示例

{
    "error_code": 0,
    "message": "OK",
    "task_id": "68753A444D6F12269C600050E4C00067",
    "task_status": "done",
    "audio_address": "https://XXX",
    "phoneme_address": "https://XXX"
}

1
2
3
4
5
6
7
8

# 3、音频/音素下载

GET方式访问合成结果中audio_address的url下载音频 GET方式访问phoneme_address下载音素信息

WARNING

注意：音频下载地址3天有效，不支持重复下载 (使用浏览器打开可能触发多次访问，导致无法播放)

# 4、音素时间戳结构说明

名称	类型	说明
sentence	String	合成文本
phoneme	Array	合成文本对应音素信息
└start	double	开始时间，单位ms
└end	double	结束时间，单位ms
└phone	String	音素值，当前音素内容
└type	int	1：字开始(声母) 4：字结束(韵母) 5：整字(复韵母) 8：静音 16、20：停顿

# 返回示例

[{
        "sentence": "你好",
        "phoneme": [
            {
                "end": 208.98,
                "phone": "sil",
                "start": 0,
                "type": 8
            },
            {
                "end": 278.639,
                "phone": "n",
                "start": 208.98,
                "type": 1
            },
            {
                "end": 417.959,
                "phone": "i",
                "start": 278.639,
                "type": 4
            },
            {
                "end": 557.279,
                "phone": "h",
                "start": 417.959,
                "type": 1
            },
            {
                "end": 801.088,
                "phone": "ao",
                "start": 557.279,
                "type": 4
            },
            {
                "end": 1001.361,
                "phone": "sil",
                "start": 801.088,
                "type": 8
            }
        ]
    }]

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

# 七、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	正常
23901	参数错误	客户端检查参数是否正确
23902	签名校验失败	参考接口鉴权中示例，检查签名
23903	服务内部错误	建议重试，或者提工单，工单详情请提供task_id
23907	套餐耗尽	购买套餐
23908	appkey不存在	检查appkey是否合法
23909	客户端ip不在白名单中	检查是否开启白名单，同时检查客户端出口ip是否在ip白名单中
23910	任务不存在	请核对接口返回的task_id
23911	文本长度不合规	文字超过5万字符，建议分段落合成

# 九、发音人列表

音库类型	发音人名称	发音人风格	发音人代码	发音人描述
精品音库	橙橙	默认	chengcheng-neutral-plus	知性大方
		开心	chengcheng-happy-plus
		生气	chengcheng-angry-plus
		厌恶	chengcheng-disgust-plus
		害怕	chengcheng-fear-plus
		难过	chengcheng-sad-plus
	莎莎	默认	shasha-neutral-plus	亲和自然
		开心	shasha-happy-plus
		生气	shasha-angry-plus
		厌恶	shasha-disgust-plus
		害怕	shasha-fear-plus
		难过	shasha-sad-plus
	晓迪	默认	xiaodi-plus	温柔舒缓
	晓迪	温暖	xiaodi-warm-plus	温柔舒缓
	Kiyo	元气	kiyo-plus	可爱女生
	Kiyo	职业	suren-plus	可爱女生
	萱萱	默认	xuanxuan-plus	甜美女生
	晓琴	默认	xiaoqin-plus	亲切温和
	Jenny	默认	jenny-plus	纯正美音
	小峰	默认	xiaofeng-plus	男播音员
	小雯	默认	xiaowen-plus	女播音员
	天天	默认	tiantian-plus	天真男孩
	糖糖	默认	tangtang-plus	活泼女孩
	珍妮	默认	zhenni-plus	异域风情
	玲玲	默认	lingling-plus	台湾女生
	晓珂	默认	xiaoke-plus	漂亮御姐
	宁宁	默认	ningning-plus	粤语女声
普通音库	Kiyo	默认	kiyo-base	可爱女生
	小雯	默认	xiaowen-base	女播音员
	小峰	默认	xiaofeng-base	男播音员
	萱萱	默认	xuanxuan-base	甜美女生
	天天	默认	tiantian-base	天真男孩
	糖糖	默认	tangtang-base	活泼女孩
	玲玲	默认	lingling-base	台湾女生

← 合成WebAPI文档概述 →