# 一、接口说明

将长文本( ≤ 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 可爱女生
职业 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 台湾女生