# 一、接口说明

将长文本（ ≤ 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 是 发音人 参考发音人列表
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="毫米汞柱">mmHg</mute>或说取消 气压的测量单位是毫米汞柱

# 八、错误码

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

# 九、发音人列表

音库类型 发音人名称 发音人风格 发音人代码 发音人描述
大模型 晨宇 默认 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 可爱女生
职业 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 台湾女生

← 概述 →