基础视频合成接口

更新时间：2025-06-19

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 时必填，字符长度不超过 20000。输入文本需包含标点符号分割，连续文本不超过1024字节，每个中文一个字按3个字节，英文字母及数字空格按1个字节计算。支持 SSML 标签，使用说明见[SSML使用说明]（仅限中文音色）(https://cloud.baidu.com/doc/AI_DH/s/rlyyduk53) • 当 lan 参数非'auto'时，请自行确认文本与所选语言是否一致，如不一致合成成功后会导致发音异常。
ttsParams	object	否	TTS 参数，当 driveType 为 TEXT 时必填
-- person	string	否	发音人ID，可用发音人列表参考：公共音色库；如果开通的声音克隆服务，也可以使用用户自己克隆的音色ID作为发音人
-- lan	string	否	注：仅有LITE版克隆音色及公共音色库中的支持多语言的音色支持该参数。 • 支持参数列表：'Chinese', 'Chinese,Yue', 'English', 'Russian', 'Spanish', 'French', 'Portuguese', 'German', 'Turkish', 'Dutch', 'Ukrainian', 'Vietnamese', 'Indonesian', 'Japanese', 'Italian', 'Korean', 'Thai', 'Polish', 'Romanian', 'Greek', 'Czech', 'Finnish', 'Hindi', 'auto'
-- 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.时长不超过 90 分钟 2.文件大小不超过2G 3.支持的音频格式为wav、mp3、wma、m4a
playControlParams	object	否	控制合成视频中人像底板视频的播放逻辑，不传则使用底板视频从头开始正反循环播放。只有用户定制的2d小样本人像可以使用此功能，公共人像，精品人像不能使用。
-- controlType	String	是	控制类型，枚举值： 1. SEGMENT_LOOP：指定底板视频片段正反循环播放，通过startTimestamp和endTimestamp选取片段；
-- startTimestamp	double	否	起始时间戳，单位是秒，支持两位小数，起始时间要小于底板视频总时长，不填默认取 0。
-- endTimestamp	double	否	结束时间戳，单位是秒，支持两位小数，结束时间不能大于底板视频总时长且要大于起始时间（起始时间和结束时间的间隔要大于0.04秒，也就是1帧），不填默认取视频结尾。
videoParams	object	是	视频参数
-- width	int	是	视频分辨率，最大不超过 4k，并且不能超过人像底板宽或高的分辨率
-- height	int	是
-- transparent	boolean	否	是否输出 webm 格式透明背景视频，false 则输出mp4格式视频，默认 true
dhParams	object	否	数字人参数，控制数字人的大小位置，目前支持三种方式，生效优先级 positionV2 > position > cameraId
-- cameraId	int	否	数字人机位，预置了数字人的位置和大小，支持的人像类型： 3D数字人、 2D精品数字人，机位 ID 点击查阅人像介绍文档
-- 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原始比例，越小数字人越小。
-- positionV2	object	否	通过剪裁方式像素级别控制数字人位置和大小，如果启用此参数，dhParams中的position 和 cameraId 参数无效，目前支持 2D小样本数字人。先根据剪裁参数（crop）从人像底板选取数字人矩形区域，然后使用位置参数（location）控制数字人区域在最终视频里的位置和大小，参考表格下面的示例图。
-- -- crop	object	否	裁剪参数，默认不裁剪，即取整个人像底板
-- -- -- top	int	否	数字人区域到人像底板顶边距离，单位：像素，默认取 0 表示取顶边，不能超过人像底板的高度
-- -- -- left	int	否	数字人区域到人像底板左边距离，单位：像素，默认取 0 表示取左边，不能超过人像底板的宽度
-- -- -- width	int	是	数字人区域的宽度，单位：像素，不能小于底板宽度的 0.1 倍，left + width 不能超过底板的宽度
-- -- -- height	int	是	数字人区域的宽度，单位：像素，不能小于底板高度的 0.1 倍，top + height 不能超过底板的高度
-- -- location	object	是	数字人区域在视频里的位置
-- -- -- top	int	否	数字人区域到视频顶边距离，单位：像素，默认取 0 表示和顶边重合，不能超过视频的高度
-- -- -- left	int	否	数字人区域到视频左边距离，单位：像素，默认取 0 表示和左边重合，不能超过视频的宽度
-- -- -- width	int	是	视频中数字人区域的宽度，单位：像素，不能随意缩放，取值范围：[crop.width * 0.3, crop.width * 1.5]
-- -- -- height	int	是	视频中数字人区域的高度，单位：像素，不能随意缩放，取值范围：[crop.height * 0.3, crop.height * 1.5]
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

positionV2 参数 crop 及 location 示例图：

positionV2 crop及location示例

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

                JavaScript
                
            

                {
    "figureId": "1081",
    "text": "嗨！我是挥手问候家，为你打造专属问候，不论早晚，挥手间温暖送达！",
    "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": 1920,
        "width": 1080,
        "transparent": false
    },
    "autoAnimoji": false,
    "subtitleParams": {
        "enabled": false,
        "subtitlePolicy": "SRT"
    },
    "callbackUrl": "http://api-gateway:8080/api/digitalhuman/internal/api-gateway/v1/callback/vp/test"
}
            

2.1.7 返回示例

                JavaScript
                
            

                {
    "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 错误码

错误码	描述
20003	inputAudioUrl 文件下载失败
20005	backgroundImageUrl 文件下载失败
20034	图片下载异常
20005	backgroundImageUrl 文件下载失败
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 请求示例

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

2.2.6 返回示例

                JavaScript
                
            

                {
  "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"
  }
}
            

照片数字人视频合成接口

高级视频合成接口

百度智能云

数字员工-开放平台