基础视频合成接口
更新时间:2024-12-13
1. 接口说明
接口调用地址:https://open.xiling.baidu.com
输入文本或音频驱动数字人生成播报视频,支持合成透明背景视频。
- 调用视频合成任务接口,提交数字人配置和驱动文本、音频,返回任务ID
- 接收任务结束的回调通知,或使用任务ID轮询任务状态(不建议)
接口鉴权和通用字段说明请查阅接口通用说明
2. 接口列表
2.1 提交视频合成任务
2.1.1 接口说明
配置数字人播报文本或音频,以及其他视频参数,提交合成任务,返回任务ID。
2.1.2 接口协议
POST /api/digitalhuman/open/v1/video/submit
Header Content-Type: application/json;charset=utf-8
2.1.3 请求参数
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
figureId | string | 是 | 人像 ID,参考人像说明文档:3D数字人、2D精品数字人、 2D小样本数字人 |
driveType | string | 否 | 驱动数字人的数据类型,枚举值,默认 TEXT。 1.TEXT:文本驱动,系统会调用 TTS 合成音频后驱动数字人 2.VOICE: 音频驱动,使用输入音频驱动数字人 |
text | string | 否 | 驱动数字人播报的文本,当 driveType 为 TEXT 时必填,字符长度不超过 2000。支持 SSML 标签,使用说明见SSML使用说明 |
ttsParams | object | 否 | TTS 参数,当 driveType 为 TEXT 时必填 |
-- person | string | 否 | 发音人ID,可用发音人列表参考:公共音色库 |
-- speed | string | 否 | 语速:5是正常值,0-15的取值范围。越大语速越快,默认值5 (字面量需要是整数) |
-- volume | string | 否 | 音量:5是正常值,0-15的取值范围,越大音量越大,默认值5 (字面量需要是整数) |
-- pitch | string | 否 | 语调:5是正常值,0-15的取值范围,越大声音越尖,默认值5 (字面量需要是整数) |
inputAudioUrl | string | 否 | 驱动数字人播报的音频 url,url 字符长度不超过 1000。当 driveType 为 VOICE 时必填。音频要求: 1.时长不超过 10 分钟 2.文件大小不超过120 MB 3.支持的音频格式为wav、mp3、wma、m4a |
videoParams | object | 是 | 视频参数 |
-- width | int | 是 | 视频分辨率,最大支持 4k,注意视频分辨率不能超过人像本身的分辨率。2k、4k 视频合成目前限时优惠,和低分辨率视频计费保持一致。注意视频的宽高必须设置为偶数。 |
-- height | int | 是 | 注意视频的宽高必须设置为偶数。 |
-- transparent | boolean | 否 | 是否输出 webm 格式透明背景视频,false 则输出mp4格式视频,默认 true |
dhParams | object | 否 | 数字人参数 |
-- cameraId | int | 否 | 数字人机位,指定了数字人的位置和大小,建议使用和视频分辨率比例一致的机位。支持的人像类型:3D数字人、2D精品数字人、2D小样本数字人 |
-- position | object | 否 | 数字人位置和大小,不能和 camera id 同时指定,支持的人像类型:3D数字人、2D精品数字人 、2D小样本数字人 |
-- -- x | float | 否 | 水平位置,范围 -0.5 到 0.5 ,取 0 居中,越大数字人越靠右 |
-- -- y | float | 否 | 竖直位置,范围 -1 到 1 ,取 0 数字人底部对齐视频底部,越大数字人越靠上 |
-- -- z | float | 否 | 缩放比例,范围 0.5 到 1.5 ,取1原始比例,越小数字人越小。注意:y 的取值是按数字人原始大小上下移动,当 z 取值大于 1,既放大数字人时,y 的值可以小于 -1 以实现更大范围下移。 |
subtitleParams | object | 否 | 字幕参数,当 driveType 为 TEXT 时生效 |
-- subtitlePolicy | string | 否 | 字幕策略,枚举值,默认:SRT,字幕信息会以 SRT 格式保存到字幕文件中,在视频信息可以获取文件 URL,字段名:subtitleFileUrl |
-- enabled | boolean | 否 | 是否开启,默认:false |
backgroundImageUrl | string | 否 | 背景图片 url,字符长度不超过 1000,图片长宽比例建议和视频分辨率保持一致,否则会进行拉伸或填充黑边。图片格式要求: 1.文件大小不超过 3 MB 2.支持的图片格式:png、jpg、jpeg、bmp |
callbackUrl | string | 否 | 接口调用方接受任务回调通知的url,规则和接口说明参考接口通用说明,回调消息定义如下表。 |
autoAnimoji | boolean | 否 | 是否自动添加数字人动作,默认值 false。生效条件: 1.值设为 true 2.支持人像:3D数字人、2D精品数字人 3.驱动方式是 TEXT |
enablePalindrome | boolean | 否 | 是否开启视频首尾帧一致,默认值 false,基于正反序播放底板视频实现,主要用于视频拼接播放场景避免衔接处跳变。支持的人像类型:2D小样本人像。 |
2.1.4 回调参数
- type: VIDEO_GENERATE
- data:
参数名 | 类型 | 是否必填 | 描述 |
---|---|---|---|
taskId | string | 是 | 任务ID |
status | string | 是 | 状态: SUCCESS(合成成功) FAILED(合成失败) |
failedCode | int | 否 | 失败错误码 |
failedMessage | string | 否 | 失败错误信息 |
videoUrl | string | 否 | 视频文件地址,文件会保存 7 天 |
duration | int | 否 | 视频时长,单位 ms |
subtitleFileUrl | string | 否 | 字幕文件地址,文件会保存 7 天 |
2.1.5 返回参数
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
taskId | string | 是 | 任务ID,用于调用任务查询接口查询任务状态 |
2.1.6 请求示例
{
"figureId": "A2A_V2-3to2_meihan",
"text": "嗨!我是挥手问候家,为你打造专属问候,不论早晚,挥手间温暖送达!",
"inputAudioUrl": "https://digital-human-pipeline-output.cdn.bcebos.com/vis/audio/a-qewefy6hd5mwaxik4s.wav",
"driveType": "TEXT",
"backgroundImageUrl": "https://meta-human-editor-prd.cdn.bcebos.com/ca1d70b6f73d44bebd2aba1f3deb60bb/draftThumbnail/dt-qfdkzu6nhawzayqb5.png",
"ttsParams": {
"person": "5116",
"speed": "5",
"pitch": "5",
"volume": "5"
},
"videoParams": {
"height": 720,
"width": 1080,
"transparent": false
},
"autoAnimoji": true,
"subtitleParams": {
"enabled": true,
"subtitlePolicy": "SRT"
},
"callbackUrl": "http://api-gateway:8080/api/digitalhuman/internal/api-gateway/v1/callback/vp/test"
}
2.1.7 返回示例
{
"code": 0,
"message": {
"global": "success"
},
"result": {
"taskId": "vid-qgti66nzkch2xy9h",
"status": null,
"failedCode": 0,
"failedMessage": null,
"videoUrl": null,
"duration": 0,
"createTime": null,
"updateTime": null,
"subtitleFileUrl": null
},
"requestId": "b978a051-fafe-4623-bfa5-1c07566e88ac",
"success": true
}
2.1.8 错误码
错误码 | 描述 |
---|---|
0 | 正常返回 |
4911 | 找不到app信息,请确认appId是否输入正确 |
4913 | 无法访问API,可能是app没有绑定对应的组件,或url输入错误,或访问的人像不可用 |
10001 | 签名校验失败 |
10002 | 签名信息为空 |
10003 | 签名格式错误 |
10004 | 未识别错误的通用错误码 |
10005 | 请求体JSON解析失败,请确认是否是合法的JSON格式 |
10006 | 参数校验不通过 |
10011 | 没有购买对应的商品 |
14001 | 内部服务异常,请稍后再试 |
14002 | 内部服务异常,网络拥堵 |
20003 | inputAudioUrl 文件下载失败 |
20005 | backgroundImageUrl 文件下载失败 |
20034 | 图片下载异常 |
20005 | backgroundImageUrl 文件下载失败 |
22001 | figureId 不存在 |
22002 | figureId 查询异常 |
22003 | figureId 无权限 |
22004 | 人像状态不可用 |
22005 | 人像分辨率过高,不能用于实时直播 |
50001 | 额度预扣除失败 |
2.2 查询任务
2.2.1 接口说明
使用任务ID查询任务状态
2.2.2 接口协议
GET /api/digitalhuman/open/v1/video/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 |
subtitleFileUrl | string | 否 | 字幕文件 URL |
createTime | string | 是 | 创建时间,示例:2024-04-29T20:28:06 |
updateTime | string | 是 | 更新时间,示例:2024-04-29T20:28:06 |
2.2.5 请求示例
GET /api/digitalhuman/open/v1/video/task?taskId=abc123&requestId=123e4567-e89b-12d3-a456-426614174000
2.2.6 返回示例
{
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"code": 0,
"success": true,
"message": {
"global": "success"
},
"result": {
"taskId": "abc123",
"status": "SUCCESS",
"failedCode": null,
"failedMessage": null,
"videoUrl": "https://example.com/video.mp4",
"duration": 300000,
"createTime": "2024-04-29T20:28:06",
"updateTime": "2024-04-29T20:28:06"
}
}