# 一、接口说明

将长文本( ≤ 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 签名 *** 必需

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 用户标识

# 2.2、请求参数示例

{
	"appkey": "45gn7md5n44aak7a57rdjud3b5l4xdgv75saomys",
	"format": "wav",
	"sign": "9204610822034a220b213a8807f362089a4a98115057e2bbb5cf42da06fe512f",
	"text": "    云知声专注于物联网人工智能服务,是一家拥有完全自主知识产权、世界顶尖智能语音技术的人工智能企业。公司成立于2012年6月,\n总部位于北京,在上海、深圳、厦门、合肥设有子公司,目前员工接超过500人。\n    从交互入手,云知声构建了语音感知、认知和表达、超算平台与图像、机器翻译等多模态人工智能硬核技术,并将这些能力封装在自研 AI 芯片之上,\n通过“云端芯”一体化产品体系面向行业推出全栈式 AI 技术能力,打造从 AI 技术创新到产业应用的生态闭环。\n    在应用层面,云知声提供跨硬件平台、跨应用场景,端云一体的人工智能整体解决方案,广泛应用于家居、医疗、金融、教育、交通、汽车、地产等领域。\n迄今为止,云知声的合作伙伴数量超 2 万家,主要客户涵盖平安、世茂、吉利、格力、美的、海尔、华为、京东、360 等头部企业,覆盖用户超 2 亿,云平台日调用量超\n5.7 亿次,覆盖设备超 2.5 亿台。\n    云知声的愿景是“智享未来”。从1956年首次提出人工智能(AI)概念开始,到现在已经60多年。随着2016年AlphaGo击败李世石,人工智能也迎来了第三次春天。\n我们认为,互联网已经经历了PC互联网、移动互联网,现在正在迈向万物智联时代。未来将从“以设备为中心”进步为“以用户为中心”,\"以数据为中心\"。万物对人\n类的服务将变得“主动”,它们通过芯片感知你的生活指标,并主动提供最舒适的服务。\n    渴了有机器人自动把水送上,饿了电饭煲自动做饭,热了空调自动开启降温,甚至连灯光也会随外界光线和你的需求变得明亮或者暗淡。而这一切,并不需要你手\n动或语言输入什么指令,只需“智享未来”。\n    从2012年成立至今,云知声汇集了一群有梦想和共同愿景的人,相信科技改变世界,人工智能会让未来生活更好。他们来自IBM、盛大、摩根大通、中科院、剑桥等\n全球顶尖公司和院校,拥有丰富的商业运营经验和深厚的技术背景,为企业发展提供了强大支撑。\n    其中,Unisound AI Labs(云知声人工智能研究院)研究员全部拥有硕士及以上学历,其中博士占比超过45%,多人具有超过十年的研发和应用经验,经过多年技术\n创新、实践和积累,云知声拥有多项自主知识产权和软件著作权。云知声的产品和运营团队则汇聚了来自纽昂斯、阿里巴巴、百度、华为、麦肯锡、闪迪、网易、蓝色\n光标等国内外知名公司的优秀人才。",
	"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天有效,不支持重复下载 (使用浏览器打开可能触发多次访问,导致无法播放)

# 六、错误码

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

# 发音人列表

音库类型 发音人代码 发音人名称 发音人描述
精品音库 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 玲玲 台湾女生