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

驱动数字人

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

描述

调用本接口，配置数字人语音驱动方式、音色、语速、语调和音量，驱动数字人说话。

接口原型

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

请求参数

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

参数	类型	是否必选	描述
TaskId	String	是	数字人视频流任务 ID，创建数字人视频流任务后获取。
Driver	Object	是	驱动配置。
DriverType	Int	是	驱动方式： 1：文本驱动。 2：音频文件驱动。 3：静音驱动。此时数字人只有动作没有声音。 4：实时音频流驱动。
TimbreId	String	否	音色 ID，DriverType 为 1 时，必填。可通过查询音色列表，了解当前数字人支持的音色。
Text	String	否	文本内容，DriverType 为 1 时，必填。不超过 1800 个字。支持 SSML标记语言。
SpeechRate	Int	否	语速，取值范围为 [-500, 500]，默认值 0。数值越大，声音越快。
PitchRate	Int	否	语调，取值范围为 [-500, 500]，默认值 0。数值越大，声音越尖。
Volume	Int	否	音量，取值范围为 [1, 100]，默认值 50。数值越大，声音越大。
AudioUrl	String	否	音频 URL 绝对链接（音频格式支持 MP3 和 WAV 文件），DriverType 为 2 时，必填，用户自定义传入。
Strategy	Int	否	打断策略： 0：（默认）排队等待前面的驱动任务完成后，再执行本驱动任务。 1：中断当前语音，立即执行本驱动任务。
Actions	Array of Object	否	插入动作，比如摊手、合上、打招呼等动作。 DriverType 为 1 时选填。 DriverType 为 2 和 4 时不生效。 DriverType 为 3 时必填。
ActionName	String	否	插入动作的名称，需联系 ZEGO 技术支持获取。
StartPos	int	否	动作插入的位置。 DriverType 为 1 时，表示在第几个字后插入。 DriverType 为 3 时，此字段不生效，立即插入。
RTCProvider	String	否	DriverType 为 4 时必传，实时语音驱动的 RTC 厂商，当前仅支持 zego。
RTCOptions	Object	否	DriverType 为 4 时必传，ZEGO RTC 驱动相关参数。
RoomId	String	是	驱动音频流所在的 RTC 房间 ID。
StreamId	String	是	驱动音频流的流 ID。
UserId	String	否	进入 RTC 房间，开发者需自定义拉取驱动音频流的用户 ID（保证房间内唯一，且不能与驱动音频流的流 ID 相同），该 UserId 仅用于在后台拉取驱动音频流，无实际意义。若不自定义系统将自动生成 UserId 用于拉取驱动音频流。

请求示例

请求 URL

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

请求消息体

{
    "TaskId": "8873388e-1710-4573-bffd-6df25fd4cb0f",
    "Driver": {
        "DriverType": 1,
        "TimbreId": "your_timebre_id",
        "Text": "时维九月，序属三秋。潦水尽而寒潭清，烟光凝而暮山紫。俨骖騑于上路，访风景于崇阿。临帝子之长洲，得天人之旧馆。层峦耸翠，上出重霄；飞阁流丹，下临无地。鹤汀凫渚，穷岛屿之萦回；桂殿兰宫，即冈峦之体势。",
        "Actions": [
           {
              "ActionName": "action_hello",
              "StartPos": 1
           }
        ]
    }
}

响应参数

参数	类型	描述
Code	Int	错误码。
Message	String	错误描述。
Data	Object	响应对象。
DriverTaskId	String	驱动数字人任务 ID，查询驱动任务状态时使用。

响应示例

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

返回码

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

返回码	说明	处理建议
0	成功。	-
100000004	签名过期。	请重新生成签名。
100000005	签名错误。	请确认生成签名的参数是否正确。
400000001	输入参数无效。	请根据 Message 提示，调整对应参数的取值。
400000002	数字人 PaaS 服务权限未开通。	请联系 ZEGO 技术支持开通服务权限。
400000004	未找到音色。	请确认设置的 TimbreId 是否正确。
400000005	未找到任务。	请确认设置的 TaskId 是否正确。
400000006	数字人视频流任务未开始。	请等待数字人视频流任务开始后再进行操作。
400000009	数字人视频流任务不支持当前音色。	请使用其它音色。
400010000	系统错误。	请联系 ZEGO 技术支持处理。