照片数字人视频合成接口

更新时间：2024-12-26

1. 接口说明

接口调用地址：https://open.xiling.baidu.com

语音驱动人像图片合成播报视频，支持合成透明背景视频。

调用视频合成任务接口，提交语音音频和图片，返回任务ID
接收任务结束的回调通知，或使用任务ID轮询任务状态（不推荐）

接口鉴权和通用字段说明请查阅：接口通用说明

注意：输入的照片需符合以下规范，否则输出视频会有异样

照片清晰，只包含单个人脸
面部正对镜头，轮郭完整
面部无明显阴影，无头发遮挡
无夸张表情，不露牙齿
背景无其他人脸、杂物

2. 接口列表

2.1 提交视频合成任务

2.1.1 接口说明

提交语音音频和人像图片，返回任务ID。合成视频的分辨率和图片一致，如果图片宽或高超过 1920，会同比例缩小至 1920。

2.1.2 接口协议

POST /api/digitalhuman/open/v1/video/image/submit

Header Content-Type: application/json;charset=utf-8

2.1.3 请求参数

参数	类型	必填	说明
inputImageUrl	string	是	人像图片 url，url 字符长度不超过 1000，图片需要包含清晰的人脸，图片格式要求： 1.文件大小不超过 3 MB； 2.支持的图片格式png、jpg、jpeg；当图片是包含透明通道的 png 格式，会返回 webm 格式透明背景视频，其他情况返回 mp4 格式视频。图片内容要求： 1.照片清晰，只有单个人脸； 2.面部正对镜头，轮廓完整； 3.面部无明显阴影，无头发遮挡； 4.无夸张表情，不露牙齿
driveType	string	否	驱动数字人的数据类型，枚举值，默认 TEXT。 1.TEXT：文本驱动，系统会调用 TTS 合成音频后驱动数字人。 2.VOICE: 音频驱动，使用输入音频驱动数字人。
text	string	否	驱动数字人播报的文本，当 driveType 为 TEXT 时必填，字符长度不超过 500。支持 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，当 driveType 为 VOICE 时必填。url 字符长度不超过 1000，音频要求： 1.时长不超过 2 分钟且不小于2秒。 2.文件大小不超过 60 MB。 3.支持的音频格式为wav、mp3、wma、m4a、aac。
callbackUrl	string	否	接口调用方接受任务回调通知的url，规则和接口说明参考接口通用说明，回调消息定义如下表。

2.1.4 回调参数

type: VIDEO_GENERATE_IMAGE
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 请求示例

{
    "requestId": "xxxx11",
    "text": "嗨！我是挥手问候家，为你打造专属问候，不论早晚，挥手间温暖送达！",
    "driveType": "TEXT",
    "ttsParams": {
        "person": 5116,
        "speed": 5,
        "pitch": 5,
        "volume": 5
    },
    "inputImageUrl": "https://meta-human-editor-prd.cdn.bcebos.com/ca1d70b6f73d44bebd2aba1f3deb60bb/draftThumbnail/dt-qfdkzu6nhawzayqb5.png",
    "inputAudioUrl": "https://digital-human-pipeline-output.cdn.bcebos.com/vis/audio/a-qewefy6hd5mwaxik4s.wav",
    "callbackUrl": "http://api-gateway:8080/api/digitalhuman/internal/api-gateway/v1/callback/vp/test"
}

2.1.7 返回示例

{
    "code": 0,
    "message": {
        "global": "success"
    },
    "result": {
        "taskId": "img-qgti819vzahqxpb3",
        "status": null,
        "failedCode": 0,
        "failedMessage": null,
        "videoUrl": null,
        "duration": 0,
        "createTime": null,
        "updateTime": null,
        "subtitleFileUrl": null
    },
    "requestId": "xxxx11",
    "success": true
}

2.1.8 错误码

错误码	描述
0	正常返回
4911	找不到app信息，请确认appId是否输入正确
4913	无法访问API，可能是app没有绑定对应的组件，或url输入错误，或访问的人像不可用
10001	签名校验失败
10002	签名信息为空
10003	签名格式错误
10004	未识别错误的通用错误码
10005	请求体JSON解析失败，请确认是否是合法的JSON格式
10006	参数校验不通过
10011	没有购买对应的商品
14001	内部服务异常，请稍后再试
14002	内部服务异常，网络拥堵
20001	未检测到合格人脸
20004	检测到多个人脸
20002	inputImageUrl 文件下载失败
20003	inputAudioUrl 文件下载失败

2.2 查询任务

2.2.1 接口说明

使用任务ID查询任务状态

2.2.2 接口协议

GET /api/digitalhuman/open/v1/video/image/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	否	字幕文件地址，文件会保存 7 天
createTime	string	是	创建时间，示例：2024-04-29T20:28:06
updateTime	string	是	更新时间，示例：2024-04-29T20:28:06

2.2.5 请求示例

GET /api/digitalhuman/open/v1/video/image/task?taskId=abc123&requestId=123e4567-e89b-12d3-a456-426614174000

2.2.6 返回示例

{
    "code": 0,
    "message": {
        "global": "success"
    },
    "result": {
        "taskId": "img-qgti819vzahqxpb3",
        "status": "GENERATING",
        "failedCode": 0,
        "failedMessage": "",
        "videoUrl": null,
        "duration": 0,
        "createTime": "2024-07-18T08:17:56",
        "updateTime": "2024-07-18T08:17:56",
        "subtitleFileUrl": ""
    },
    "requestId": "fdc66116-762d-4a82-a082-e83357a3167e",
    "success": true
}

2.3 人像图片校验

2.3.1 接口说明

检测人像图片是否符合视频合成的要求。非必须，如果业务场景交互流程需要可以提前做人像校验。

2.3.2 接口协议

POST /api/digitalhuman/open/v1/video/image/verify