CreateLiveDigitalHumanAgentInstance

2026-08-25

POST

https://aigc-aiagent-api.zegotech.cn/

With this interface, you can create a live digital human agent instance and join the agent instance into a voice (RTC) conversation, or push the video stream to third-party platforms (such as Facebook, TikTok, etc.).

Note

By default, each account can have at most 10 digital human agent instances. If the limit is exceeded, the creation of a digital human agent instance will fail. If you need to adjust this limit, please contact ZEGOCLOUD Technical Support.

Request

Query Parameters

Action stringrequired

Possible values: [CreateLiveDigitalHumanAgentInstance]

Interface prototype parameters

https://aigc-aiagent-api.zegotech.cn?Action=CreateLiveDigitalHumanAgentInstance

AppId uint32required

💡Public parameter. Application ID, assigned by ZEGOCLOUD. Get it from the ZEGOCLOUD Admin Console.

SignatureNonce stringrequired

💡Public parameter. A 16-character hexadecimal random string (hex encoding of 8-byte random number). Refer to Signature sample code for how to generate.

Timestamp int64required

💡Public parameter. Current Unix timestamp, in seconds. Refer to Signature sample code for how to generate, with a maximum error of 10 minutes.

Signature stringrequired

💡Public parameter. Signature, used to verify the legitimacy of the request. Refer to Signing the requests for how to generate an API request signature.

SignatureVersion stringrequired

Possible values: [2.0]

Default value: 2.0

💡Public parameter. Signature version number.

application/json

Body

required

AgentId stringrequired

The unique identifier of the registered AI agent.

RTC object

RTC related information (live digital human scenario)

- All property character limits: only numbers, English characters, '_', '-', '.' are supported
- UserStreamId is not required in the live digital human scenario
- RTC and CDN configurations are mutually exclusive. If both are set, CDN takes precedence

RoomId stringrequired

Possible values: <= 128 characters

RTC room ID.

AgentStreamId stringrequired

Possible values: <= 128 characters

The stream ID used by the agent instance for streaming.

📌 Important

Ensure that multiple concurrently running agent instances (even if not in the same RTC room) use different stream IDs, otherwise the later created agent instance will fail to stream.

AgentUserId stringrequired

Possible values: <= 32 characters

The user ID of the agent instance.

📌 Important

Ensure that multiple concurrently running agent instances (even if not in the same RTC room) use different user IDs, otherwise the earlier created agent instance will be kicked out of the RTC room.

StreamExtraInfo string

Possible values: <= 1024 characters

The stream extra info set when the Agent streams, a string of no more than 1024 bytes. The client can listen via the onRoomStreamExtraInfoUpdate callback.

CDN object

CDN push streaming configuration.

RTC and CDN configurations are mutually exclusive. If both are set, CDN takes precedence.

Url stringrequired

CDN push streaming URL.

TTS object

Vendor stringrequired

Possible values: [Aliyun, ByteDanceV3, ByteDanceFlowing, MiniMax, CosyVoice]

The TTS service provider. Please refer to Configuring TTS > TTS Parameters for details.

Url string

TTS service domain URL address, defaulting to the domestic cluster address of the corresponding vendor, e.g., MiniMax: wss://api.minimaxi.com/ws/v1/t2a_v2.

Params objectrequired

TTS configuration parameters, in JSON object format. Contains app parameters (for authentication) and other parameters (for adjusting TTS effects). Please refer to Configuring TTS > TTS Parameters for details.

app objectrequired

Used for TTS service authentication, the structure of the app parameter required by different Vendor values is different, please refer to Configuring TTS > Params Parameters for details.

other_params string

📌 Important Note

other_params is not a valid parameter, it is only to explain how to pass the vendor parameters. Except for the app parameter, other parameters are directly passed to the vendor parameters. Please refer to Configuring TTS > Params Parameters for details.

FilterText object[]

Filters out the text enclosed by specified punctuation marks from the input content to TTS (usually the content returned by LLM or the Text parameter of the SendAgentInstanceTTS API), and then performs speech synthesis. For example, in “(happily said) Welcome to ZEGOCLOUD!”, the content within the parentheses is filtered out before synthesis.

Note

- Typically, you guide the LLM via prompts in LLM > SystemPrompt to specify which parts of the content should be enclosed within particular punctuation.
- This parameter cannot be updated when updating an agent instance.

Array[

BeginCharacters stringrequired

The start punctuation mark of the filtered text. For example, if you want to filter the content in (), set it to (.

EndCharacters stringrequired

The end punctuation mark of the filtered text. For example, if you want to filter the content in (), set it to ).

]

TerminatorText string

Possible values: <= 4 characters

Can be used to set the termination text for TTS. If the input to TTS (usually the content returned by LLM or the Text parameter of the SendAgentInstanceTTS API) contains the TerminatorText string, then the content from the TerminatorText string (inclusive) onward will no longer be synthesized in this TTS round.

📌 Important Note

For bidirectional streaming, only one character can be set.

Typically, the LLM is guided via prompts in LLM > SystemPrompt to specify which parts of the content should be enclosed with special punctuation.

This parameter cannot be updated when updating an agent instance.

CharacterFilter string[]

The specified strings in the content input to TTS (usually the content returned by LLM or the Text parameter of the SendAgentInstanceTTS API) will not be involved in speech synthesis. Each string in the array indicates a string to be filtered out, and each string can have up to 2 characters.

CallbackConfig object

Server callback configuration (live digital human scenario)

📌 Important

Before configuring the following parameters, you need to refer to Receiving Callbacks to set up the callback URL and understand the specific field descriptions.

Interrupted integer

Possible values: [0, 1]

Default value: 0

Whether to enable server callback for agent interruption results.

AgentInstanceStatus integer

Possible values: [0, 1]

Default value: 0

Whether to enable server callback for agent instance status.

HostTag string

You can set up to two callback URLs to monitor events that occur during the conversation between the user and the agent. Use this parameter to specify which address the instance's event callbacks should be routed to. The specific tag value needs to be pre-configured by contacting ZEGOCLOUD Technical Support.

AdvancedConfig object

Advanced configuration (live digital human scenario).

MaxIdleTime integer

Possible values: >= 30 and <= 86400

Default value: 900

Auto-destruction time of the agent instance. The maximum idle duration of the digital human. If the digital human is not driven by the SendAgentInstanceTTS interface for this duration, the task will automatically end. Unit: seconds, value range [30, 86400], default value is 900 seconds (15 minutes).

DisableTTS boolean

Default value: false

Whether to disable TTS. If set to true, the agent instance will not perform speech synthesis.

📌 Important

When DisableTTS is true, calling Create A Live Digital Human Agent Instance and Send TTS interfaces will return an error.

TTSParamPaths object

TTS vendors can control synthesized voice emotion effects through certain parameters. This parameter controls how metadata flags in LLM output are mapped to TTS emotion control parameters. Multiple string key-value pairs can be set.

For example: "TTSParamPaths": {"instruction": "payload.parameters.instruction"}

When LLM output is [[{"instruction":"speak in a gentle tone"}]]Hello, the value speak in a gentle tone of the instruction key in the metadata {"instruction":"speak in a gentle tone"} will be extracted and passed as the payload.parameters.instruction parameter to the TTS vendor interface.
The key of TTSParamPaths can be customized according to business logic (e.g., changing instruction to i), as long as the metadata key in the LLM output matches the key defined in TTSParamPaths.

property name* string

DigitalHuman objectrequired

DigitalHumanId stringrequired

Digital human ID

ConfigId string

Possible values: [mobile, web]

Digital human configuration ID

EncodeCode string

Possible values: [H264]

Default value: H264

Digital human video encoding format

Responses

Success

application/json

Schema
Example (from schema)

Schema

Code integer

Return code. 0 indicates success, other values indicate failure. For more information on error codes and response handling recommendations, please refer to Return Codes.

Message string

Explanation of the request result

RequestId string

Request ID

Data object

AgentInstanceId string

The unique identifier of the AI agent instance.

DigitalHumanConfig string

Digital human configuration, used by the digital human mobile SDK.

{
  "Code": 0,
  "Message": "Success",
  "RequestId": "8825223157230377926",
  "Data": {
    "AgentInstanceId": "1912122918452641792",
    "DigitalHumanConfig": "eyJEaWdpdGFsSHVtYW5JZCI6ImU1ODNkMzVmLTk3OTMtNDJiNC1hYjFiLTE4OWEzNWI4OGQxYyIsIlN0cmVhbXMiOlt7IlJvb21JZCI6ImlyXzU1NTd5bDVoIiwiU3RyZWFtSWQiOiJpcl81NTU3eWw1aF8xNzEwMl9hZ2VudCIsIkVuY29kZUNvZGUiOiJIMjY0IiwiQ29uZmlnSWQiOiJ3ZWIifV19"
  }
}

{
  "Code": 0,
  "Message": "Success",
  "RequestId": "8825223157230377926",
  "Data": {
    "AgentInstanceId": "1912122918452641792",
    "DigitalHumanConfig": "eyJEaWdpdGFsSHVtYW5JZCI6ImU1ODNkMzVmLTk3OTMtNDJiNC1hYjFiLTE4OWEzNWI4OGQxYyIsIlN0cmVhbXMiOlt7IlJvb21JZCI6ImlyXzU1NTd5bDVoIiwiU3RyZWFtSWQiOiJpcl81NTU3eWw1aF8xNzEwMl9hZ2VudCIsIkVuY29kZUNvZGUiOiJIMjY0IiwiQ29uZmlnSWQiOiJ3ZWIifV19"
  }
}