虚拟人合成|AI文字转视频-云知声虚拟人合成

一、接口说明
二、接口要求
三、IP白名单
四、接口调用流程
五、TTS标签
六、错误码
七、发音人列表
八、数字人形象列表
九、背景图像列表

# 一、接口说明

虚拟人视频合成服务是将文本（ ≤ 5000 字符）转换成数字人视频，平台会基于数字人播报的文本智能同步驱动数字人做出相应的嘴型、表情和动作，同时将渲染的数字人画面合成指定格式的视频文件。

# 二、接口要求

虚拟人视频合成API时，需按照以下要求：

内容	说明
请求协议	http[s] （为提高安全性，强烈推荐https）
请求方式	POST
请求地址	http[s]: //ai-api.hivoice.cn/api/vms/ai-vms-nrt
接口鉴权	签名机制，详情请参照下方接口鉴权
字符编码	UTF-8
响应格式	统一采用JSON格式
开发语言	任意，只要可以向服务发起发起HTTP请求的均可
操作系统	任意
视频格式	mp4

# 三、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、接口鉴权

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

参数名称	参数类型	是否必填	参数说明
appKey	String	Y	调用者应用的appKey
timestamp	String	Y	时间戳字段(毫秒)
signature	String	Y	签名，参考如下签名加密函数，签名字段：appKey、timestamp、secret（顺序不可变）

# 1.1、鉴权方法

signature生成规则： A）将上述参数按照appkey、timestamp、secret secret查询 (opens new window) 顺序拼接字符串；
B）将A形成字符串获取SHA256摘要，形成一个64位的十六进制（字母大写）字符串，即为本次请求signature（签名）的值；

# 1.2、鉴权示例代码

/**
* 热词签名获取方法
* @param appkey
* @param timestamp
* @param secret
* @return
*/
public static void main(String[] args) throws Exception {
    String appkey = "45gn7md5n44******gv75saomys";
    String timestamp = System.currentTimeMillis()+"";
    String appSecret = "ba24a917a******b82a72e0d896";
  
    List<String> paramsList =
    Arrays.asList(
            appkey,
            timestamp,
            appSecret
    );
  
    System.out.println(buildSignature(paramsList));
}
  
public static String buildSignature(List<String> paramsList) {
    StringBuilder sb = new StringBuilder();
    for (String param : paramsList) {
        sb.append(param);
    }
    return getSHA256Digest(sb.toString());
}
  
private static String getSHA256Digest(String data) {
    String digest = null;
    try {
        MessageDigest md = MessageDigest.getInstance("SHA-256");
        byte[] bytes = md.digest(data.getBytes("UTF-8"));
        digest = byte2hex(bytes);
    } catch (Exception e) {
        logger.error("get bytes error ", e);
    }
    return digest;
}
  
private static String byte2hex(byte[] bytes) {
    StringBuilder sign = new StringBuilder();
    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());
    }
    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
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54

# 2、开始合成

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

协议	URL	方法
HTTP/HTTPS	http://ai-api.hivoice.cn/api/vms/ai-vms-nrt/start	POST

# 2.1、参数说明

参数名	类型	必传	描述	可选值	默认值
text	string	是	需要合成的文本
speech_param	Object	是
speech_param.vcn	string	是	发音人	参考发音人列表
speech_param.speed	int	否	语速	0~100 50
speech_param.volume	int	否	音量	0~100	50
speech_param.pitch	int	否	音高	0~100	50
speech_param.bright	int	否	亮度	50~100	50
video_param	Object	是
video_param.template	String	是	数字人模板	参考数字人形象列表
video_param.watermask	int	是	水印	0是不加，1是加
video_param.background	int是	是否使用背景 0是使用，1是不使用
video_param.backgroundImage	String	是	背景图片	参考背景图片列表
type	int	是	方式	2 通过文本合成
user_id	string	否	用户标识

# 2.2、请求参数示例

{
	"speech_param": {
		"bright": 50,
		"pitch": 50,
		"speed": 50,
		"vcn": "xuanxuan-plus",
		"volume": 50
	},
	"text": "云知声专注于物联网人工智能服务，是一家拥有完全自主知识产权、世界顶尖智能语音技术的人工智能企业。",
	"type": 2,
	"user_id": "unisound-vms-nrt-demo",
	"video_param": {
		"background": 1,
		"backgroundImage": "color_lightgreen.png",
		"template": "yadi_01",
		"watermask": 1
	}
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# 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://ai-api.hivoice.cn/api/vms/ai-vms-nrt/progress	POST

# 3.1、参数说明

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

# 3.2、请求参数示例

{
    "task_id": "68753A444D6F12269C600050E4C00067"
}

1
2
3

# 3.3、响应结果

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

# 3.4、响应结果示例

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

1
2
3
4
5
6
7

# 4、视频下载

GET方式访问合成结果中video_address的url下载视频

WARNING

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

# 五、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	文本长度不合规	文字超过5000字符

# 七、发音人列表

音库类型	发音人名称	发音人风格	发音人代码	发音人描述
精品音库	橙橙	默认	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	可爱女生
	Kiyo	职业	suren-plus	可爱女生
	萱萱	默认	xuanxuan-plus	甜美女生
	萱萱	端庄	xuanxuan-dignified-plus	甜美女生
	晓琴	默认	xiaoqin-plus	亲切温和
	Jenny	默认	jenny-plus	纯正美音
	小雯	默认	xiaowen-plus	女播音员
	小雯	庄重	xiaowen-solemn-plus	女播音员
	糖糖	默认	tangtang-plus	活泼女孩
	珍妮	默认	zhenni-plus	异域风情
	玲玲	默认	lingling-plus	台湾女生
	晓珂	默认	xiaoke-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	成熟温和
	天天	默认	tiantian-plus	天真男孩
	小峰	默认	xiaofeng-plus	男播音员
	小亮	默认	xiaoliang-plus	清朗明快
	明宇	默认	mingyu-plus	稳重浑厚
	Tiffany	默认	tiffany-plus	纯正美音
	johnny-plus	默认	tiffany-plus	纯正美音

# 八、数字人形象列表

虚拟人姓名	推荐场景	形象代码
伯轩	新闻主播	boxuan_01
伯豪	展厅讲解	bohao_01
诗涵	景点讲解	shihan_01
诗晴	智能客服	shiqing_01
欣怡	带货主播	xinyi_01
欣瑶	展厅讲解	xinyao_01
晓莹	带货主播	xiaoying_01
晓琳	景点讲解	xiaolin_01
依彤	新闻主播	yitong_01
依娜	展厅讲解	yina_01
娅迪	场馆讲解	yadi_01
玥宜	智能客服	yueyi_01

# 九、背景图像列表

序号	背景图像名称
1	bg.png
2	lightgreen.png
3	color.png
4	image_1.png
5	color_darkgreen.png
6	color_blue.png
7	color_green.png
8	color_orange.png
9	image_12.png
10	image_7.png