文档中心
aigc_server 数字人 PaaS 服务
文档中心
体验 App
SDK 中心
API 中心
常见问题
代码市场
进入控制台
立即注册
登录
中文站 English
  • 文档中心
  • 数字人 PaaS 服务
  • 服务端 API
  • 实时流式视频合成
  • 创建数字人视频流任务

服务端 API 版块于4月16日至5月15日升级维护,期间暂停信息更新,如有任何疑问,请联系ZEGO技术支持。

创建数字人视频流任务

更新时间: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 资源不足。 请稍后重试。
本篇目录
  • 免费试用
  • 提交工单
    咨询集成、功能及报价等问题
    电话咨询
    400 1006 604
    咨询客服
    微信扫码,24h在线

    联系我们

  • 文档反馈