高级视频合成接口
更新时间:2025-01-10
1. 接口说明
接口调用地址:https://open.xiling.baidu.com
基于预置模板样式,传入播报文本、视频标题、logo、背景图等素材,合成数字人播报视频。
- 调用视频合成任务接口,提交数字人配置和驱动文本、返回任务ID
- 接收任务结束的回调通知,或使用任务ID轮询任务状态(不推荐)
接口鉴权和通用字段说明请查阅接口通用说明
2. 接口列表
2.1 提交视频合成任务
2.1.1 接口说明
配置数字人播报文本或音频,以及其他视频参数,提交合成任务,返回任务ID。
2.1.2 接口协议
POST /api/digitalhuman/open/v1/video/advanced/submit
Header Content-Type: application/json;charset=utf-8
2.1.3 请求参数
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
figureId | string | 是 | 人像 ID,人像列表详见:2D小样本数字人 (仅支持2D小样本站姿人像) |
templateId | string | 是 | 模板 ID,详见 附.《高级视频模板列表》 |
driveType | string | 否 | 驱动数字人的数据类型,枚举值,默认 TEXT。 1.TEXT:文本驱动,系统会调用 TTS 合成音频后驱动数字人 2.VOICE: 音频驱动,使用输入音频驱动数字人 |
inputAudioUrl | string | 否 | 驱动数字人播报的音频 url,url 字符长度不超过 1000。当 driveType 为 VOICE 时必填。音频要求: 1.时长不超过 10 分钟 2.文件大小不超过120 MB 3.支持的音频格式为wav、mp3、wma、m4a |
text | string | 是 | 驱动数字人播报的文本,字符长度不超过 2000。支持 SSML 标签,使用说明详见:SSML使用说明 |
title | string | 否 | 视频标题,标题的文本内容,如果缺省则视频中没有标题,长度限制30 |
logoParams | object | 否 | logo |
-- logoUrl | string | 否 | logo图片的 url,如果缺省则视频中没有logo,长度限制1000,图片格式要求: 1. 文件大小不超过 3 MB 2. 支持的图片格式:png、jpg、jpeg、bmp |
bgmParams | object | 否 | bgm |
-- bgmUrl | string | 否 | bgm 的 url,长度限制 1000,音频要求: 1. 文件大小不超过 120 MB 2. 支持的音频格式:wav、mp3、wma、m4a |
materialUrl | string | 否 | 背景素材 url,支持图片和视频,长度限制1000,视频长度大于播报长度截取前面的部分,小于则循环播放。 图片格式要求: 1. 文件大小不超过 3 MB 2. 支持的图片格式:png、jpg、jpeg、bmp 视频格式要求: 1. 文件大小不超过 500 MB 2. 支持的视频格式:mp4 |
ttsParams | object | 是 | TTS 参数 |
-- person | string | 否 | 发音人ID,音色库列表详见:公共音色库 |
-- speed | string | 否 | 语速:5是正常值,0-15的取值范围。越大语速越快,默认值5 (字面量需要是整数) |
-- volume | string | 否 | 音量:5是正常值,0-15的取值范围,越大音量越大,默认值5 (字面量需要是整数) |
-- pitch | string | 否 | 语调:5是正常值,0-15的取值范围,越大声音越尖,默认值5 (字面量需要是整数) |
videoParams | object | 是 | 视频参数 |
-- width | int | 是 | 视频分辨率,需要和模板分辨率比例保持一致,最大不超过 1080x1920 或 1920x1080 |
-- height | int | 是 | 视频分辨率,需要和模板分辨率比例保持一致,最大不超过 1080x1920 或 1920x1080 |
callbackUrl | string | 否 | 接口调用方接受任务回调通知的 url,规则和接口说明参考接口通用说明 回调消息定义如下表 |
riskTip | string | 否 | 水印描述,不超过30个字,默认底部居中 (原saas水印字段,已有,这次开放) |
openingMaterial | object | 否 | 片头背景素材,传一个素材对象,格式: 1. 视频格式: mp4 2. 文件大小不超过 500 MB |
-- fileId | string | 否 | 使用openingMaterial时候,fileId和fileUrl二者必须选一必填, fileId,使用文件上传接口接口上传后获取文件ID,providerType 参数固定填写 OPEN_VIDEO_DURATION_VIDEO,如果fileId和fileUrl都填写,会用fileId,fileUrl无效 |
-- fileUrl | string | 否 | 使用openingMaterial时候,fileId和fileUrl二者必须选一必填,文件的url(必须是bos地址,bcebos.com域名下) |
-- mediaType | string | 否 | 使用openingMaterial必填,媒体类型,枚举: VIDEO |
endingMaterial | object | 否 | 片尾背景素材,传一个素材对象,格式: 1. 视频格式: mp4 2. 文件大小不超过 500 MB |
-- fileId | string | 否 | 使用endingMaterial时候,fileId和fileUrl二者必须选一必填, fileId,使用文件上传接口接口上传后获取文件ID,providerType 参数固定填写 OPEN_VIDEO_DURATION_VIDEO,如果fileId和fileUrl都填写,会用fileId,fileUrl无效 |
-- fileUrl | string | 否 | 使用endingMaterial时候,fileId和fileUrl二者必须选一必填,文件的url(必须是bos地址,bcebos.com域名下) |
-- mediaType | string | 否 | 使用endingMaterial必填,媒体类型,枚举: VIDEO |
mashupMaterials | object | 否 | 混剪背景素材,传一个素材对象的数组,最多可以传10个,视频切割成5-8s,图片随机播放3-5s,把所有素材混合后随机播放,格式: 1. 视频格式: mp4 2. 图片格式: png、jpg、jpeg、bmp 3. 文件大小视频不超过 500 MB, 图片不超过3MB |
-- fileId | string | 否 | 使用mashupMaterials时候,fileId和fileUrl二者必须选一必填, fileId,使用文件上传接口接口上传后获取文件ID,providerType 参数固定填写 OPEN_VIDEO_DURATION_VIDEO,如果fileId和fileUrl都填写,会用fileId,fileUrl无效 |
-- fileUrl | string | 否 | 使用mashupMaterials时候,fileId和fileUrl二者必须选一必填,文件的url(必须是bos地址,bcebos.com域名下) |
-- mediaType | string | 否 | 使用mashupMaterials必填,媒体类型,枚举: VIDEO ,IMAGE |
fissionParams | object | 否 | 裂变参数,使用figureId和ttsPerson组合生成多个视频 |
-- figureIds | List<string> | 否 | 人像裂变参数,使用fissionParams必传,人像id数组,传入会使用裂变功能,会覆盖figureId参数, 最多可以传10个人像ID |
-- ttsPersons | List<string> | 否 | 音色列表参数,音色id数组,如果如果不传默认只按人像id裂变,如果传入且driveType为text时会覆盖ttsParam的person参数,如果driveType为voice时,该tts参数无效,只按figureId进行裂变, 最多可以传10个音色值 |
2.1.4 回调参数
- type: VIDEO_GENERATE_ADVANCED
- data:
参数名 | 类型 | 是否必填 | 描述 |
---|---|---|---|
taskId | string | 是 | 任务ID |
status | string | 是 | 状态: SUCCESS(合成成功) FAILED(合成失败) |
failedCode | int | 否 | 失败错误码 |
failedMessage | string | 否 | 失败错误信息 |
videoUrl | string | 否 | 视频文件地址,文件会保存 7 天 |
duration | int | 否 | 视频时长,单位 ms |
2.1.5 返回参数
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
taskId | string | 是 | 任务ID,用于调用任务查询接口查询任务状态 |
fissionTasks | List<object> | 否 | 使用裂变功能(请求的fissionParams有值且通过校验生效)时返回,格式为一个对象数组,包含任务执行的信息 |
-- taskId | string | 否 | 任务id,使用是原参数的taskId无效,code为0是才返回的才是有效的id |
-- message | string | 否 | 任务执行的具体情况,成功为SUCCESS |
-- code | int | 否 | 错误码,0为正常返回 |
-- figureId | string | 否 | 人像id,当前task使用的人像Id |
-- ttsPerson | string | 否 | 音色值,当前task使用的音色值 |
2.1.6 请求示例
{
"figureId": "1081",
"templateId": "t-ad4eeqsspfzwyqxyte125",
"text": "有人说家是温馨的港湾。有人说家是心灵的寄托。如果您正在为家装而发愁,不妨考虑与我们合作。让我们为您解决装修的烦恼,让您的家焕然一新,焕发新生。点击下方联系我们,获取福利吧。",
"inputAudioUrl": "https://digital-human-pipeline-output.cdn.bcebos.com/vis/audio/a-qewefy6hd5mwaxik4s.wav",
"driveType": "TEXT",
"title": "家装盛典福利等你来",
"logoParams": {
"logoUrl": "https://meta-human-editor-test.cdn.bcebos.com/7e430c5bd2084a00b90a83f5190f6fec/f47fc33a-d63f-4bd0-815b-387cd0f373fc/logo%E7%99%BD.png"
},
"ttsParams": {
"person": "5116",
"speed": "5",
"volume": "5",
"pitch": "5"
},
"riskTip": "@baidu水印",
"openingMaterial":
{
"fileUrl": "https://meta-human-editor-test.bj.bcebos.com/fishion-test/output.mp4",
"mediaType": "VIDEO"
},
"endingMaterial":
{
"fileUrl": "https://meta-human-editor-test.bj.bcebos.com/fishion-test/output2.mp4",
"mediaType": "VIDEO"
},
"mashupMaterials": [
{
"fileUrl": "https://meta-human-editor-test.bj.bcebos.com/fishion-test/0fea7f8524371b55eaf5eb987.jpg",
"mediaType": "IMAGE"
},
{
"fileUrl": "https://meta-human-editor-test.bj.bcebos.com/fishion-test/7052b61826fae54158fea02ba.png",
"mediaType": "IMAGE"
},
{
"fileUrl": "https://meta-human-editor-test.bj.bcebos.com/fishion-test/output3.mp4",
"mediaType": "VIDEO"
}
],
"videoParams": {
"width": 1080,
"height": 1920
},
"fissionParams" : {
"figureIds": ["1081",
"1112"],
"ttsPersons": ["4100",
"5132"]
}
}
2.1.7 返回示例
{
"code": 0,
"message": {
"global": "success"
},
"result": {
"taskId": null,
"status": null,
"failedCode": 0,
"failedMessage": null,
"videoUrl": null,
"duration": 0,
"createTime": null,
"updateTime": null,
"fissionTasks": [
{
"taskId": "adv-qmutfwsptw57zegc-1112-4100",
"message": "SUCCESS",
"figureId": "xxx",
"ttsPerson": "xxx",
"code": 0
},
{
"taskId": "adv-qmutfwsptw57zegc-1081-5132",
"message": "SUCCESS",
"figureId": "xxx",
"ttsPerson": "xxx",
"code": 0
},
{
"taskId": "adv-qmutfwsptw57zegc-1081-4100",
"message": "SUCCESS",
"figureId": "xxx",
"ttsPerson": "xxx",
"code": 0
},
{
"taskId": "adv-qmutfwsptw57zegc-1112-5132",
"message": "SUCCESS",
"figureId": "xxx",
"ttsPerson": "xxx",
"code": 0
}
]
},
"requestId": "c5434cbd-c144-4a5a-8133-d6ef46c5f84b",
"success": true
}
2.1.8 错误码
错误码 | 描述 |
---|---|
0 | 正常返回 |
4911 | 找不到app信息,请确认appId是否输入正确 |
4913 | 无法访问API,可能是app没有绑定对应的组件,或url输入错误,或访问的人像不可用 |
10001 | 签名校验失败 |
10002 | 签名信息为空 |
10003 | 签名格式错误 |
10004 | 未识别错误的通用错误码 |
10005 | 请求体JSON解析失败,请确认是否是合法的JSON格式 |
10006 | 参数校验不通过 |
10011 | 没有购买对应的商品 |
14001 | 内部服务异常,请稍后再试 |
14002 | 内部服务异常,网络拥堵 |
50001 | 冻结额度失败 |
20005 | 背景图下载失败 |
20036 | 视频任务提交失败 |
10006 | 参数校验失败 |
2.2查询任务接口
2.2.1 接口说明
使用任务ID查询任务状态
2.2.2 接口协议
GET /api/digitalhuman/open/v1/video/advanced/task
2.2.3 GET 请求参数
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
taskId | string | 是 | 任务ID |
2.2.4 返回参数
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
taskId | string | 是 | 任务ID |
status | string | 是 | 状态: SUBMIT(已提交待合成) GENERATING(合成中) SUCCESS(合成成功) FAILED(合成失败) |
failedCode | int | 否 | 失败错误码 |
failedMessage | string | 否 | 失败错误信息 |
videoUrl | string | 否 | 视频文件地址,文件会保存 7 天 |
duration | int | 否 | 视频时长,单位 ms |
createTime | string | 是 | 创建时间,示例:2024-04-29T20:28:06 |
updateTime | string | 是 | 更新时间,示例:2024-04-29T20:28:06 |
2.2.5 请求示例
GET /api/digitalhuman/open/v1/video/advanced/task?taskId=adv-qgti5xjyxx6e8yxu&requestId=123e4567-e89b-12d3-a456-426614174000
2.2.6 返回示例
{
"code": 0,
"message": {
"global": "success"
},
"result": {
"taskId": "adv-qhfrtb627i772vvj",
"status": "GENERATING",
"failedCode": 0,
"failedMessage": "OK",
"videoUrl": "",
"duration": 20060,
"createTime": "2024-08-06T15:17:46",
"updateTime": "2024-08-06T15:17:46",
"subtitleFileUrl": null
},
"requestId": "f5d816ec-1938-4fd7-960c-f140b65414d2",
"success": true
}
附. 高级视频合成列表
序号 | templateId | 比例 | 模板预览 | demo视频 |
---|---|---|---|---|
1 | t-pf4kqasspwzwyexyte121 | 竖屏(9:16) | 1 | |
2 | t-af4keqsspfzwyexyte123 | 竖屏(9:16) | ||
3 | t-ad4eeqsspfzwyqxyte125 | 竖屏(9:16) | ||
4 | t-cd4eeqsspfzwyqxyte127 | 竖屏(9:16) | ||
5 | t-hb4eeqsspfzwyqxyte129 | 横屏(16:9) | ||
6 | t-cd4eeqsspfzwyqxyteditu3 | 竖屏(9:16) | ||
7 | t-cd4eeqsspfzwyqxyteditu4 | 竖屏(9:16) |