# 一、接口说明

虚拟人视频合成服务是将文本( ≤ 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 可爱女生
职业 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