离线数字人
新华智云离线数字人API,提供2D仿真数字人、3D写实数字人统一API合成服务
前提准备
标题部分 前提准备1. 域名及请求加签
标题部分 1. 域名及请求加签域名说明
2. 数字人列表查询接口
标题部分 2. 数字人列表查询接口2.1 接口调用
标题部分 2.1 接口调用- 请求地址:/open/digitalMan/pageQuery?pageNo=1&pageSize=10
- 请求方式:GET
- 说明:查询结果不包含声音及服饰信息
请求参数说明:
字段 | 是否必填 | 类型 | 说明 |
---|---|---|---|
pageNo | 是 | Integer | 分页页码 |
pageSize | 是 | Integer | 分页大小 |
2.2 接口结果
标题部分 2.2 接口结果{
"pageNo":1,
"pageSize":10,
"total":321,
"data":[{
"id":12,
"name":"云小鹿",
"description":"测试数字人的描述呀",
"preImg":"https://wordcup-entity.oss-cn-hangzhou.aliyuncs.com/virtual_host/resource/hosts/clear_virtual_xhzy_peiran_4_xhzy_2x_full.png",
"tenantId":"xxxxxx"
}]
}
参数说明:
字段 | 类型 | 说明 |
---|---|---|
pageNo | Integer | 分页页码 |
pageSize | Integer | 分页大小 |
total | Integer | 数据总量 |
data | JSONArray | 数字人信息 |
data结构:
字段 | 类型 | 说明 |
---|---|---|
id | Long | 数字人id |
name | String | 名称 |
description | String | 描述 |
preImg | String | 预览图 |
tenantId | String | 租户ID |
3. 数字人详情查询接口
标题部分 3. 数字人详情查询接口3.1 接口调用
标题部分 3.1 接口调用- 请求地址:/open/digitalMan/detaiQuery/{id}
- 请求方式:GET
- 请求参数:数字人id,必填
3.2 接口结果
标题部分 3.2 接口结果{
"success": true,
"data": {
"id": 12,
"name": "云小鹿",
"description": "测试数字人的描述呀",
"preImg": "https://wordcup-entity.oss-cn-hangzhou.aliyuncs.com/virtual_host/resource/hosts/clear_virtual_xhzy_peiran_4_xhzy_2x_full.png",
"tenantId": "xxxxxx",
"voices": [
{
"gender": "female",
"name": "小云(标准)",
"voiceId": "1",
"type": "Alibaba",
"maxVolume": 100,
"minVolume": 0,
"maxSpeed": 500,
"minSpeed": -500,
"maxTone": 500,
"minTone": -500,
"onTop": 0,
"per": "1"
}
],
"clothes": [
{
"code": "91",
"audioGenerate": "true",
"fullBodyImg": "https://wordcup-entity.oss-cn-hangzhou.aliyuncs.com/virtual_host/resource/hosts/clear_virtual_xhzy_peiran_4_xhzy_2x_full.png",
"cameraStands": [
{
"code": "front",
"description": "正机位",
"imgUrl": "https://wordcup-entity.oss-cn-hangzhou.aliyuncs.com/virtual_host/resource/hosts/clear_virtual_xhzy_peiran_4_xhzy_2x_full.png"
}
],
"emotions": [
{
"code": "12",
"imgUrl": "https://wordcup-entity.oss-cn-hangzhou.aliyuncs.com/virtual_host/resource/hosts/clear_virtual_xhzy_peiran_4_xhzy_2x_full.png",
"name": "测试情绪",
"actions": [
{
"code": "123",
"imgUrl": "https://wordcup-entity.oss-cn-hangzhou.aliyuncs.com/virtual_host/resource/hosts/clear_virtual_xhzy_peiran_4_xhzy_2x_full.png",
"name": "测试动作"
}
]
}
]
}
]
}
}
参数说明:
字段 | 类型 | 说明 |
---|---|---|
voices | JSONArray | 数字人声音 |
clothes | JSONArray | 数字人服饰 |
其余字段 | 同2.2中data参数 |
voices结构:
字段 | 类型 | 说明 |
---|---|---|
gender | String | 发音人性别 |
name | String | 名称 |
voiceId | String | 声音ID(注:4.1算法调用时tts字段中per取该值) |
type | String | 类型 |
maxVolume | Integer | 最大音量,用于4.1中tts音量可选范围 |
minVolume | Integer | 最小音量,用于4.1中tts音量可选范围 |
maxRate | Integer | 最大语速,用于4.1中tts语速可选范围 |
minRate | Integer | 最小语速,用于4.1中tts语速可选范围 |
maxPitch | Integer | 最大语调,用于4.1中tts语调可选范围 |
minPitch | Integer | 最小语调,用于4.1中tts语调可选范围 |
onTop | Integer | 置顶顺序 |
clothes结构:
字段 | 类型 | 说明 |
---|---|---|
code | String | 服饰code(注:4.1算法调用时avatar参数取该值) |
fullBodyImg | String | 全身图 |
audioGenerate | Boolean | 是否支持音频驱动 |
cameraStands | JSONArray | 机位 |
emotions | JSONArray | 情绪集合(包含动作列表) |
cameraStands结构:
字段 | 类型 | 说明 |
---|---|---|
code | String | 机位code(注:4.1算法调用时speak标签中的camera标签取该值) |
description | String | 描述 |
imgUrl | String | 图片 |
emotions结构:
字段 | 类型 | 说明 |
---|---|---|
code | String | 情绪code(注:4.1算法调用时speak标签中的emotion标签取该值) |
name | String | 名称 |
imgUrl | String | 图片 |
actions | JSONArray | 关联的动作 |
actions结构:
字段 | 类型 | 说明 |
---|---|---|
code | String | 动作code(注:4.1算法调用时speak标签中的motion标签取该值) |
name | String | 名称 |
imgUrl | String | 图片 |
4. 数字人合成相关接口
标题部分 4. 数字人合成相关接口4.1 合成接口调用
标题部分 4.1 合成接口调用- 请求地址:/open/digitalMan/batch/generate
- 请求方式:POST
- 请求参数:
{
"generateParam": [
{
"algoParam": {
"video": {
"width": 1080,
"height": 1920
},
"background": "https://wordcup-entity.oss-cn-hangzhou.aliyuncs.com/virtual_host/resource/green_16_9.jpg",
"tts": {
"text": "<speak rate=\"0\" pitch=\"0\" volume=\"50\">你好吗 今天天气真好</speak>",
"per": "1012"
},
"position": [
0,
0,
1080,
1801
],
"code": "50",
"is_green": true,
"subtitle": true
}
}
],
"callBackUrl":"http://xxxxxxx"
}
参数说明:
字段 | 是否必须 | 类型 | 说明 |
---|---|---|---|
generateParam | 是 | JSONArray | 合成参数 |
callBackUrl | 否 | String | 合成回调地址,回调方式需遵循4.5异步回调方式进行设计 |
generateParam结构:
字段 | 是否必填 | 类型 | 说明 |
---|---|---|---|
algoParam | 是 | JSONObject | 单个数字人合成任务的参数 |
extra | 否 | JSONObject | 业务扩展字段,结果查询时会透传 |
algoParam结构:
字段 | 是否必填 | 类型 | 说明 |
---|---|---|---|
video | 是 | JSONObject | 视频宽高 |
background | 是 | String | 视频背景 |
tts | 否 | JSONObject | 所需播报内容以及声音id,tts和audio_url必选一个 |
audio_url | 否 | String | 数字人详情字段中audioGenerate为ture时支持音频驱动,tts和audio_url必选一个,音频格式支持wav、pcm、mp3 |
position | 是 | JSONArray | 数字人在视频中占位[x,y,w,h] |
code | 是 | String | 数字人唯一编码 |
is_green | 否 | Boolean | 是否是绿幕背景,默认false |
subtitle | 否 | Boolean | 结果是否需要返回字幕,默认false |
tts结构:
字段 | 是否必填 | 类型 | 说明 |
---|---|---|---|
text | 是 | String | 所需播报文本 |
per | 是 | String | 播报内容时所用声音id |
说明:
- tts中的text字段可以带多个speak标签。
- speak标签中可以插入停顿,如:
<speak>测试<break time="500ms"/>一下</speak>
- <speak>标签可以设置属性,用于控制语音合成参数,也可控制控制主播表情、动作、机位,如:
- rate用于控制TTS语速,
- pitch用于控制TTS语调
- volume用于控制TTS音量
- motion用于控制主播动作
- emotion用于控制主播表情
- camera用于控制机位,3d主播才有
<speak rate="100" pitch="100" volume="100" motion="1" emotion="2" camera="left">今天是个好日子</speak>
- <speak>标签支持属性:
- 语音停顿:<break>
- 指定单个汉字的读音:<phoneme>
- 指定分词:<w>
指定分词 <w>
- 描述用于表示文本的词语结构,该标签是可选标签。英文文本通常采用空格来进行分词,一般无需使用此标签。<w>标签内部必须是一个独立的词或短语,这个词或短语不允许混合使用中文和其他外语。
例子:
<speak>南京市长<w>江大桥</w>今天发表了演讲。</speak>
语音停顿 <break>
- 描述用于在文本中插入停顿,该标签是可选标签。
- 属性说明
使用无属性的<break>标签时,停顿时长为“1s”。
属性名称 | 属性类型 | 属性值 | 是否必选 | 描述 |
---|---|---|---|---|
time | String | [number]s/[number]ms | 否 | 以秒/毫秒为单位设置停顿的时长 (如“2s“、“50ms”)。 |
- [number]s:以秒为单位,[number]取值范围为[1, 10]的整数。
- [number]ms:以毫秒为单位,[number]取值范围为[50, 10000]的整数。 |
例子:
<speak>
请闭上眼睛休息一下<break time="500ms"/>好了,请睁开眼睛。
</speak>
指定单个汉字的读音 <phoneme>
- 描述用于控制标签内文本的读音,该标签是可选标签。英文文本不支持该标签。
- 属性描述
属性名称 | 属性类型 | 属性值 | 是否必选 | 描述 |
---|---|---|---|---|
alphabet | String | py | 是 | “py”表示拼音。 |
ph | String | 标签内文本对应的拼音串 | 是 | 拼音用法的赋值规范: |
- 字与字的拼音用空格分隔,拼音的数目必须与字数相等。
- 每个拼音由发音和音调组成,音调为1~5的数字编号,其中”5”表示轻声。
例子:
<speak>
去<phoneme alphabet="py" ph="dian3 dang4 hang2">典当行</phoneme>把这个玩意<phoneme alphabet="py" ph="dang4 diao4">当掉</phoneme>
</speak>
- audio_url需按<url>标签进行指定,相关标签内属性同上speak标签 例子:
<url rate="0" volume="50" motion="100" emotion="0" pitch="0" camera="front">
https://video-mock.oss-cn-hangzhou.aliyuncs.com/upload/audio/mobile/df51e416-b0c5-4dff-bc91-84b78d7b65ec.mp3
</url>
4.2 合成接口结果
标题部分 4.2 合成接口结果调用成功会返回任务的groupId
{
"success": true,
"code": "",
"msg": "",
"requestId": "",
"data": "vh_05d8811ef2fe41ecb487af9c10ff20fe"
}
4.3 合成任务查询接口
标题部分 4.3 合成任务查询接口- 请求地址:/open/digitalMan/batch/query/{groupId}
- 请求方式:GET
- 请求参数:groupId
4.4 合成任务结果返回
标题部分 4.4 合成任务结果返回{
"success": true,
"code": "",
"msg": "",
"requestId": "",
"data": [
{
"id": "vh_25c8eaaebfaf4406b0f9fa92edd58bb7",
"status": "completed",
"duration": 3120.0,
"composeUrl": "http://wordcup-entity.oss-cn-hangzhou.aliyuncs.com/virtual_host/2022-05-23/c4838efb-e24f-4678-80a3-601ce3f5d6ac.mp4",
"alphaVideoUrl": "http://wordcup-entity.oss-cn-hangzhou.aliyuncs.com/virtual_host/2022-05-23/32ecdb1f-e581-4b39-9dcb-45033ac38f91.mp4",
"textSegs": [
{
"text": "你好吗 今天天气真好",
"startTime": 200,
"endTime": 2490
}
],
"extra": null,
"errorMsg": null
}
]
}
参数说明:
字段 | 类型 | 说明 |
---|---|---|
id | String | 任务id |
status | String | 当前子任务合成状态 |
duration | Double | 当前子任务视频的总时长,单位(毫秒) |
composeUrl | String | 当前子任务的合成视频,返回智云云上OSS地址,存在临时生命周期,建议客户自行转存(生命周期三个月) |
alphaVideoUrl | String | 当前子任务的alpha通道视频,返回智云云上OSS地址,存在临时生命周期,建议客户自行转存(生命周期三个月) |
textSegs | JSONArray | 当前子任务所播报内容的相关信息,可用于字幕合成,详见5.1 |
extra | String | 业务扩展字段,透传 |
errorMsg | String | 合成失败时的错误信息,详见7. |
textSegs结构:
字段 | 类型 | 说明 |
---|---|---|
text | String | 文本内容 |
startTime | String | 文本内容开始播报时间,单位(毫秒) |
endTime | String | 文本内容结束播报时间,单位(毫秒) |
status结构: | 枚举类型 | 说明 | | | --- | --- | | | fail | 子任务合成失败,常见原因请见7. | | | waiting | 子任务正在合成中 | | | completed | 子任务合成完成 | |
4.5 异步回调方式
标题部分 4.5 异步回调方式智云请求客户回调地址时,会根据客户aksk进行简单的签名字段生成,客户依据签名校验判断请求是否来自智云,防止对公的回调地址被攻击
统一异步回调aksk验证方式请移动网关认证文档 网关接入文档。
业务自定义的请求体内容:
{
"code": 200,
"message": "",
"data": {
"id": "vh_25c8eaaebfaf4406b0f9fa92edd58bb7",
"status": "completed",
"duration": 3120.0,
"composeUrl": "http://wordcup-entity.oss-cn-hangzhou.aliyuncs.com/virtual_host/2022-05-23/c4838efb-e24f-4678-80a3-601ce3f5d6ac.mp4",
"alphaVideoUrl": "http://wordcup-entity.oss-cn-hangzhou.aliyuncs.com/virtual_host/2022-05-23/32ecdb1f-e581-4b39-9dcb-45033ac38f91.mp4",
"textSegs": [
{
"text": "你好吗 今天天气真好",
"startTime": 200,
"endTime": 2490
}
],
"extra": null,
"errorMsg": null
},
"groupId": "vh_25c8eaaebfaf4406b0f9fa92edd58bb0"
}
5. 字幕文件生成
标题部分 5. 字幕文件生成5.1 接口调用
标题部分 5.1 接口调用请求地址:/open/digitalMan/subtitle/generate 请求方式:POST 请求参数:
{
"taskId":"vh_aac24aa2841547399978fc6fccfb6e92",
"type":"ass"
}
参数说明:
字段 | 类型 | 说明 |
---|---|---|
taskId | String | 任务id,取4.4合成返回结果中的id |
type | String | 字幕类型,默认srt,可选ass |
5.2 合成结果
标题部分 5.2 合成结果{
"success":true,
"code":"",
"msg":"",
"requestId":"",
"data":"https://xhzy-aiprod-production-template-manage.oss-cn-hangzhou.aliyuncs.com/vhost/subtitle/test/85180252-77da-418e-a9ff-893078bb2f4c.ass"
}
返回结果:
字段 | 类型 | 说明 |
---|---|---|
data | String | 字幕ASS文件,,返回智云云上OSS地址,存在临时生命周期,建议客户自行转存(生命周期三个月) |
6. 接口请求失败常见错误码
标题部分 6. 接口请求失败常见错误码失败code码:
错误码 | 说明 |
---|---|
SW-DM-1000 | 数字人合成任务创建失败 |
SW-DM-1001 | 租户ID缺失 |
SW-DM-1002 | 主参数缺失 |
SW-DM-1003 | generateParam参数缺失 |
SW-DM-1004 | generateParam.algoParam参数缺失 |
SW-DM-1005 | generateParam.algoParam.code数字人形象code参数缺失 |
SW-DM-1006 | generateParam.algoParam.tts数字人tts参数缺失 |
SW-DM-1007 | 当前租户无权限合成该数字人code |
SW-DM-1008 | generateParam.algoParam.tts.per参数缺失 |
SW-DM-1009 | 传输的声音ID校验不通过,请从数字人详情中获取对应的voiceId |
SW-DM-1010 | 传输的数字人code校验不通过,请从数字人详情中clothes列表中获取对应的code字段值 |
SW-DM-1011 | 当前数字人未有声音和形象列表 |