文档中心
数字人 PaaS 服务
服务端 API
精品数字人异步合成
创建视频合成任务

创建视频合成任务

更新时间：2025-04-15 19:16

描述

调用本接口，传入数字人形象、素材、背景、驱动参数、视频参数和字幕生成等参数，创建一个数字人视频合成任务。

接口原型

请求方法：POST
中国大陆正式环境请求地址：https://aigc-api.zegotech.cn/?Action=CreateMetaHumanVideo
传输协议：HTTPS
调用频率限制：10 次/秒

请求参数

以下请求参数列表仅列出了接口请求参数，公共参数列表请参考调用方式 - 公共请求参数。

参数	类型	是否必选	描述
MetaHuman	Object	是	数字人形象配置。
MetaHumanId	String	是	数字人形象 ID，通过查询数字人模特详情获得。
Layout	Object	是	数字人形象布局。
Top	Int	是	距离输出画布上边框的像素大小。用户自定义传入。
Left	Int	是	距离输出画布左边框的像素大小。用户自定义传入。
Width	Int	是	布局宽度。用户自定义传入。
Height	Int	是	布局高度。用户自定义传入。
Layer	Int	否	图层，必须大于等于 0，数值越大则图层越靠前。用户自定义传入。
StartFrame	String	否	起始帧。用户自定义传入。从数字人的源视频中选取一帧作为起始帧，视频从此帧开始推理，作为视频的首帧，且视频的最后一帧也将为该起始帧。此参数为空，则随机选取源视频任意帧作为起始帧。起始帧格式为“时：分：秒：帧”，例如“00:00:02:21”，表示取数字人源视频第 2 秒 21 帧作为起始帧。
Assets	Array of Object	否	素材配置。
AssetType	Int	是	素材类型，只支持 1（图片）。
AssetUrl	String	是	素材 URL。
Layout	Object	是	素材布局。
Top	Int	是	布局左上角的 y 轴坐标。用户自定义传入。
Left	Int	是	布局左上角的 x 轴坐标。用户自定义传入。
Width	Int	是	布局宽度。用户自定义传入。
Height	Int	是	布局高度。用户自定义传入。
Layer	Int	否	图层，必须大于等于 0，数值越大则图层越靠前。用户自定义传入。
BackgroundColor	String	否	背景颜色，十六进制的 RGB 值，格式如“#ffffff”，默认值为“#000000”（黑色）。用户自定义传入。
Driver	Object	是	驱动配置。
DriverType	Int	是	驱动方式。 1：文本驱动。 2：音频驱动。
TimbreId	String	DriverType 为 1 时，必填	音色 ID。可通过查询音色列表，了解当前数字人支持的音色。
Text	String	DriverType 为 1 时，必填	文本内容。不超过 1800 个字。支持 SSML标记语言。
SpeechRate	Int	否	语速，取值范围为 [-500, 500]，默认值 0。数值越大，声音越快。
PitchRate	Int	否	语调，取值范围为 [-500, 500]，默认值 0。数值越大，声音越尖。
Volume	Int	否	音量，取值范围为 [1, 100]，默认值 50。数值越大，声音越大。
AudioUrl	String	DriverType 为 2 时，必填	音频 URL。用户自定义传入。
VideoOption	Object	是	视频参数配置。
Width	Int	是	合成视频的分辨率，宽，不超过 2560，且 Width 和 Height 的乘积不超过 2560 * 1440。用户自定义传入。
Height	Int	是	合成视频的分辨率，高，不超过 2560，且 Width 和 Height 的乘积不超过 2560 * 1440。用户自定义传入。
Format	String	否	文件格式，必须为“mp4”或“webm”，默认值为“mp4”。
Subtitle	Object	否	字幕配置。
Enable	Int	否	是否生成字幕文件，默认为 0。 0：不生成。 1：生成。如果为文本驱动，生成字幕不涉及计费。如果为音频驱动，生成字幕需要收取 ASR 费用，详情请联系 ZEGO 商务人员。

请求示例

请求 URL

https://aigc-api.zegotech.cn/?Action=CreateMetaHumanVideo
&AppId=1234567890
&SignatureNonce=15215528852396
&Timestamp=1234567890
&Signature=7a2c0f11145fb760d607a07b54825013
&SignatureVersion=2.0

请求消息体

{
    "MetaHuman": {
        "MetaHumanId": "your_meta_human_id",
        "Layout": {
            "Top": 191,
            "Left": 100,
            "Width": 506,
            "Height": 900,
            "Layer": 0
        }
    },
    "BackgroundColor": "#000000",
    "Driver": {
        "DriverType": 1,
        "TimbreId": "your_timebre_id",
        "Text": "时维九月，序属三秋。潦水尽而寒潭清，烟光凝而暮山紫。俨骖騑于上路，访风景于崇阿。临帝子之长洲，得天人之旧馆。层峦耸翠，上出重霄；飞阁流丹，下临无地。鹤汀凫渚，穷岛屿之萦回；桂殿兰宫，即冈峦之体势。"
    },
    "VideoOption": {
        "Width": 1280,
        "Height": 720
    }
}

响应参数

参数	类型	描述
Code	Int	错误码。
Message	String	错误描述。
Data	Object	响应对象。
TaskId	String	视频合成任务 ID。获取任务 ID 后，请查询视频合成任务传入此 ID，获取相关视频、音频和字幕下载 URL。

响应示例

{
    "Code": 0,
    "Message": "succeed",
    "Data": {
        "TaskId": "XXXXXXXXXXXX",
    }
}

返回码

以下仅列出了常见的接口业务逻辑相关的返回码，完整返回码请参考全局返回码。

返回码	说明	处理建议
0	成功。	-
100000004	签名过期。	请重新生成签名。
100000005	签名错误。	请确认生成签名的参数是否正确。
400000001	输入参数无效。	请根据 Message 提示，调整对应参数的取值。
400000002	数字人 PaaS 服务权限未开通。	请联系 ZEGO 技术支持开通服务权限。
400000003	未找到数字人形象。	请确认设置的 MetaHumanId 是否正确。
400000004	未找到音色。	请确认设置的 TimbreId 是否正确。
400010000	系统错误。	请联系 ZEGO 技术支持处理。
400010001	未获得接口调用权限。	请联系 ZEGO 技术支持开通服务权限。