Drive Digital Human with Text

2026-03-20

Description

Through this API, you can make the Digital Human broadcast the specified input text. If you have not integrated any TTS provider, you can directly drive the Digital Human by passing in text. ZEGOCLOUD supports using public timbres from Volcengine (Doubao) and MiniMax to drive the Digital Human.

Request prototype

Request method: POST
Request body format: JSON
Request URL: https://aigc-digitalhuman-api.zegotech.cn?Action=DriveByText
Transmission protocol: HTTPS
QPS limit: 10 times/second

Request Parameters

The following request parameter list only includes API request parameters and some common parameters. For the complete list of common parameters, please refer to API Calling Methods - Common Request Parameters.

Parameter	Type	Required	Description
TaskId	String	Yes	Digital Human video stream task ID. Obtained from the response parameter of the Create Digital Human Video Stream Task API.
Text	String	Yes	Broadcast text content. Up to 1800 characters.
InterruptMode	Number	No	Whether to interrupt the currently executing broadcast task and immediately execute this task. Options: 0 (default): No, queue and wait for the previous task to complete before executing. 1: Yes, immediately interrupt the current task and execute this task.
TTSConfig	Object	Yes	TTS related configuration. For the structure of this parameter, refer to TTSConfig.

TTSConfig

Parameter	Type	Required	Description
TimbreId	String	Yes	Timbre ID. Obtained from the response parameter of the Get Timbre List API.
SpeechRate	Number	No	Speech rate. Ranges from [-500, 500]. If not specified, defaults to 0. Higher values mean faster speech rate.
PitchRate	Number	No	Pitch. Ranges from [-500, 500]. If not specified, defaults to 0. Higher values mean higher pitch.
Volume	Number	No	Volume. Ranges from [1, 100]. If not specified, defaults to 50. Higher values mean louder volume.

Request Example

Request URL:

https://aigc-digitalhuman-api.zegotech.cn?Action=DriveByText
&<common-request-parameters>

https://aigc-digitalhuman-api.zegotech.cn?Action=DriveByText
&<common-request-parameters>

Request body:

{
    "TaskId": "f06d1f5d-c0d1-4845-9a2c-f0a45ee037fd",
    "Text": "xxx",
    "TTSConfig": {
        "Volume": 51,
        "SpeechRate": 51,
        "PitchRate": 51,
        "TimbreId": "xxx"
    },
    "InterruptMode": 1
}

{
    "TaskId": "f06d1f5d-c0d1-4845-9a2c-f0a45ee037fd",
    "Text": "xxx",
    "TTSConfig": {
        "Volume": 51,
        "SpeechRate": 51,
        "PitchRate": 51,
        "TimbreId": "xxx"
    },
    "InterruptMode": 1
}

Response Parameters

Parameter	Type	Description
Code	Number	Return code. 0 indicates success, other values indicate failure. For error codes and response handling recommendations, please refer to Return Codes.
Message	String	Description of the request result.
RequestId	String	Request ID.
└DriveId	String	Digital Human video stream drive task ID.

Response Example

{
    "Code": 0,
    "Message": "success",
    "RequestId": "e6f95291-7053-4c87-9bd0-b4b8c56aabfd",
    "Data": {
        "DriveId": "ae8c4d88-44fe-469a-aedf-df06849d0fdc"
    }
}

{
    "Code": 0,
    "Message": "success",
    "RequestId": "e6f95291-7053-4c87-9bd0-b4b8c56aabfd",
    "Data": {
        "DriveId": "ae8c4d88-44fe-469a-aedf-df06849d0fdc"
    }
}