文档中心
数字人 PaaS 服务
服务端 API
实时流式视频合成
创建数字人视频流任务

创建数字人视频流任务

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

描述

调用本接口创建一个数字人视频流任务，配置数字人形象、素材、背景、视频参数及视频流任务时长等参数。调用此接口后，数字人相关的视觉元素即可出现在画面。但此时数字人还不能说话，如需实现数字人语音，请参考驱动数字人。

本服务端接口仅支持向 ZEGO RTC 房间推流，需要搭配实时音视频一起使用。

接口原型

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

请求参数

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

参数	类型	是否必选	描述
StreamType	String	否	流类型: rtc（默认）、rtmp
RtmpUrl	String	若 StreamType 为 rtmp 时，必填	rtmp 流地址，用户自定义传入。
RoomId	String	是	推流到指定房间 ID，长度在 128 字节以内，用户自定义传入。
StreamId	String	是	流 ID，长度在 256 字节以内，仅支持数字，英文字符和 ‘-’，’_’。请注意，StreamId 必须是 AppID 全局内唯一，用户自定义传入。
MetaHuman	Object	是	数字人形象配置。
MetaHumanId	String	是	数字人形象 ID，通过查询数字人模特列表获得。
Layout	Object	是	数字人形象布局。
Top	Int	是	布局左上角的 y 轴坐标。
Left	Int	是	布局左上角的 x 轴坐标。
Width	Int	是	布局宽度。
Height	Int	是	布局高度。
Layer	Int	否	图层，必须大于等于 0，数值越大则图层越靠前。
Assets	Array of Object	否	素材配置。
AssetType	Int	是	素材类型。 1：图片。
AssetUrl	String	是	素材 URL，用户自定义传入。
Layout	Object	是	素材布局。
Top	Int	是	距离输出画布上边框的像素大小。
Left	Int	是	距离输出画布左边框的像素大小。
Width	Int	是	布局宽度。
Height	Int	是	布局高度。
Layer	Int	否	图层，必须大于等于 0，数值越大则图层越靠前。
BackgroundColor	String	否	背景颜色，十六进制的 RGB 值，格式如“#ffffff”，默认值为“#000000”（黑色）。注意：图片数字人不支持该字段。
VideoOption	Object	是	视频参数配置。
Width	Int	是	视频流分辨率，宽，不超过 2560，且 Width 和 Height 的乘积不超过 2560 * 1440。
Height	Int	是	视频流分辨率，高，不超过 2560，且 Width 和 Height 的乘积不超过 2560 * 1440。
MaxLiveTime	Int	否	数字人视频流任务最大时长，持续时间达到该值自动结束。单位为秒，默认值 86400 秒（24 小时），最大不超过 86400（24 小时）。
BackgroundMode	Int	否	0：默认背景。 1：开启背景透明通道。仅当开发者使用原生平台 Express SDK 拉流时，才可以实现背景透明通道。原生平台开发者在接入 Express SDK 过程中，如果有背景叠加渲染需求，在本参数设置为 1（开启背景透明通道）后，需在 ZegoCanvas 对象下开启 alphaBlend（允许 Alpha 混合图层渲染，默认关闭，需手动开启）即可。

请求示例

请求 URL

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

请求消息体

{
    "StreamType": "rtc",
    "RtmpUrl": "",
    "StreamId": "your_stream_id",
    "MetaHuman": {
        "MetaHumanId": "your_meta_human_id",
        "Layout": {
            "Top": 191,
            "Left": 100,
            "Width": 506,
            "Height": 900,
            "Layer": 0
        }
    },
    "BackgroundColor": "#000000",
    "VideoOption": {
        "Width": 1280,
        "Height": 720
    },
    "MaxLiveTime": 3600,
    "BackgroundMode": 0
}

响应参数

参数	类型	描述
Code	Int	错误码。
Message	String	错误描述。
Data	Object	响应对象。
TaskId	String	数字人视频流任务 ID，查询时使用。

响应示例

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

返回码

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

返回码	说明	处理建议
0	成功。	-
100000004	签名过期。	请重新生成签名。
100000005	签名错误。	请确认生成签名的参数是否正确。
400000001	输入参数无效。	请根据 Message 提示，调整对应参数的取值。
400000002	数字人 PaaS 服务权限未开通。	请联系 ZEGO 技术支持开通服务权限。
400000003	未找到数字人形象。	请确认设置的 MetaHumanId 是否正确。
400000008	并发数超出限制。	请确认当前创建的并发数量是否超过上限。
400000010	数字人形象内部配置出错问题。	可先使用其他 MetaHumanId 及时创建视频流任务，随后联系 ZEGO 技术支持调整内部配置。
400000015	当前流 ID 已存在。	请更换流 ID 或结束当前流任务。
400000016	数字人模型版本错误。	请联系 ZEGO 技术支持处理。
400010000	系统错误。	请联系 ZEGO 技术支持处理。
400010001	未获得接口调用权限。	请联系 ZEGO 技术支持开通服务权限。
400010002	资源不足。	请稍后重试。