CreateLiveDigitalHumanAgentInstance

2026-07-27

POST

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

通过本接口，您可以创建播报数字人智能体实例，并将智能体实例加入到语音（RTC）对话之中，或将画面推流到第三方平台（如 Facebook、TikTok 等）。

注意

默认情况下一个账号下最多同时存在 10 个数字人智能体实例，超过限制后创建数字人智能体实例会失败，如需调整请联系 ZEGO 商务。

Request

Query Parameters

Action string必填

可选值: [CreateLiveDigitalHumanAgentInstance]

接口原型参数

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

AppId uint32必填

💡公共参数。应用 Id，由 ZEGO 分配的用户唯一凭证。可从 ZEGO 控制台获取。

SignatureNonce string必填

💡公共参数。16 位 16 进制随机字符串（8 字节随机数的 hex 编码）。生成算法可参考签名示例。

Timestamp int64必填

💡公共参数。当前 Unix 时间戳，单位为秒。生成算法可参考签名示例，最多允许 10 分钟的误差。

Signature string必填

💡公共参数。签名，用于验证请求的合法性。请参考签名机制生成。

SignatureVersion string必填

可选值: [2.0]

默认值: 2.0

💡公共参数。签名版本号。

application/json

Body

required

AgentId string必填

已注册的智能体唯一标识符

RTC object

RTC 相关信息（播报数字人场景）

- 所有属性字符限制：仅支持数字、英文字符、'_'、'-'、'.'
- 播报数字人场景下不需要 UserStreamId
- RTC 与 CDN 配置二选一。如果两个都设置，以 CDN 为准

RoomId string必填

可选值: <= 128 characters

RTC 房间 ID。

AgentStreamId string必填

可选值: <= 128 characters

智能体实例推流使用的流 ID。

📌 重要说明

请确保当前运行中的多个智能体实例（即便不在同一个 RTC 房间）使用不同的流 ID，否则会导致后创建的智能体实例推流失败。

AgentUserId string必填

可选值: <= 32 characters

智能体实例的用户 ID。

📌 重要说明

需确保同时在运行中的多个智能体实例（即便不在同一个 RTC 房间）使用不同的用户 ID，否则先创建的智能体实例会被踢出 RTC 房间。

StreamExtraInfo string

可选值: <= 1024 characters

Agent 推流时设置的流附加信息，长度不超过1024字节的字符串。客户端可以通过 onRoomStreamExtraInfoUpdate 回调监听。

CDN object

CDN 推流配置。

RTC 与 CDN 配置二选一。如果两个都设置，以 CDN 为准。

Url string必填

CDN 推流地址。

TTS object

Vendor string必填

可选值: [Aliyun, ByteDanceV3, ByteDanceFlowing, MiniMax, CosyVoice]

语音合成（TTS）服务提供商。详细请参考配置 TTS > TTS 参数说明

Url string

TTS 服务域名 URL 地址，默认为对应厂商的国内集群地址，如 MiniMax：wss://api.minimaxi.com/ws/v1/t2a_v2。

Params objectrequired

TTS 配置参数，格式为 JSON 对象。包含 app 参数（用于认证）和其他参数（用于调整 TTS 效果）。详细请参考配置 TTS > Params 参数说明

app object必填

用于 TTS 服务鉴权，不同的 Vendor 值要求传入的 app 参数的结构不同，详细请参考配置 TTS > Params 参数说明

other_params string

📌 重要说明

other_params 不是一个有效参数，仅仅是为了说明如何透传厂商参数。除 app 参数外，其余参数均直接透传厂商参数。详细请参考配置 TTS > Params 参数说明

FilterText object[]

从输入给 TTS 的内容中（一般是 LLM 返回的内容或者 SendAgentInstanceTTS 接口的 Text 参数值）过滤掉指定标点符号内的文本，然后再进行语音合成。比如把“(开心的说)即构科技欢迎你！”括号内的内容过滤掉，再进行语音合成。

说明

- 通常是在 LLM > SystemPrompt 中通过提示词的方式指引 LLM 哪些内容应该放在指定标点符号内。
- 此参数在更新智能体实例时无法更新。

Array[

BeginCharacters string必填

过滤文本的开始标点符号。例如，如果要过滤 () 中的内容，请设置为 (。

EndCharacters string必填

过滤文本的结束标点符号。例如，如果要过滤 () 中的内容，请设置为 )。

]

TerminatorText string

可选值: <= 4 characters

可用于设置 TTS 的终止文本。若输入给 TTS 的内容中（一般是 LLM 返回的内容或者 SendAgentInstanceTTS 接口的 Text 参数值）出现匹配 TerminatorText 字符串的内容，则本轮 TTS 从 TerminatorText 字符串（包含）开始的内容将不再进行语音合成。

📌 重要说明

双向流式只能设置一个字符。

通常是在 LLM > SystemPrompt 中通过提示词的方式指引 LLM 哪些内容应该放在指定标点符号内。

此参数在更新智能体实例时无法更新。

CharacterFilter string[]

输入给 TTS 的内容中（一般是 LLM 返回的内容或者 SendAgentInstanceTTS 接口的 Text 参数值）指定的字符串不参与语音合成。数组内每个字符串代表一个要被过滤掉的字符串，每个字符串不超过 2 个字符。

CallbackConfig object

服务端回调配置（播报数字人场景）

📌 重要说明

在配置以下参数前，你需要参考接收回调设置好回调地址，并了解具体字段说明。

Interrupted integer

可选值: [0, 1]

默认值: 0

是否开启服务端回调智能体被打断结果。

AgentInstanceStatus integer

可选值: [0, 1]

默认值: 0

是否开启服务端回调智能体实例状态的回调。

HostTag string

可以设置最多两个回调地址用于监听用户与智能体对话过程中所发生的事件。通过该参数指定该实例的事件回调到哪个地址。具体 tag 值需联系 ZEGO 技术支持预先配置好。

AdvancedConfig object

高级配置（播报数字人场景）。

MaxIdleTime integer

可选值: >= 30 and <= 86400

默认值: 900

智能体实例的自动销毁时间。数字人最大空闲时长，持续达到该时间未调用 SendAgentInstanceTTS 接口驱动数字人，任务将自动结束。单位为秒，取值范围 [30, 86400]，默认值为 900 秒（15 分钟）。

DisableTTS boolean

默认值: false

是否禁用 TTS 功能。如果设置为 true，则智能体实例不会进行语音合成。

📌 重要说明

DisableTTS 为 true 时，调用创建播报数字人智能体实例及主动调用 TTS接口都会报错。

TTSParamPaths object

TTS 各家厂商可以通过一些参数控制合成的语音情绪效果。这个参数控制 LLM 输出内容中如何通过元数据标志映射为 TTS 情绪控制参数。该参数可以设置多个 string 类型的键值对。

比如："TTSParamPaths": {"instruction": "payload.parameters.instruction"}

表示 LLM 输出为 [[{"instruction":"用温柔的语气"}]]你好 时，会将这段输出中的元数据 {"instruction":"用温柔的语气"} 的 instruction 对应的值 用温柔的语气 提取出来，作为值传给 TTS 厂商接口的 payload.parameters.instruction 参数。
TTSParamPaths 的 key 可以根据业务逻辑自定义（例如将 instruction 换成 i），只需保证 LLM 输出的元数据 key 与 TTSParamPaths 中定义的 key 一致即可。

property name* string

DigitalHuman objectrequired

DigitalHumanId string必填

数字人形象 ID

ConfigId string

可选值: [mobile, web]

数字人配置 ID

EncodeCode string

可选值: [H264]

默认值: H264

数字人视频编码格式

Responses

创建成功

application/json

数据结构
按数据结构生成的示例

Schema

Code integer

返回码，0 表示成功，其他值表示失败。详情请参考返回码说明。

Message string

请求结果说明

RequestId string

请求 ID

Data object

AgentInstanceId string

智能体实例的唯一标识。

DigitalHumanConfig string

数字人配置，给数字人移动端 SDK 使用。

{
  "Code": 0,
  "Message": "success",
  "RequestId": "3151527792559699732",
  "Data": {
    "AgentInstanceId": "1912122918452641792",
    "DigitalHumanConfig": "eyJEaWdpdGFsSHVtYW5JZCI6ImU1ODNkMzVmLTk3OTMtNDJiNC1hYjFiLTE4OWEzNWI4OGQxYyIsIlN0cmVhbXMiOlt7IlJvb21JZCI6ImlyXzU1NTd5bDVoIiwiU3RyZWFtSWQiOiJpcl81NTU3eWw1aF8xNzEwMl9hZ2VudCIsIkVuY29kZUNvZGUiOiJIMjY0IiwiQ29uZmlnSWQiOiJ3ZWIifV19"
  }
}

{
  "Code": 0,
  "Message": "success",
  "RequestId": "3151527792559699732",
  "Data": {
    "AgentInstanceId": "1912122918452641792",
    "DigitalHumanConfig": "eyJEaWdpdGFsSHVtYW5JZCI6ImU1ODNkMzVmLTk3OTMtNDJiNC1hYjFiLTE4OWEzNWI4OGQxYyIsIlN0cmVhbXMiOlt7IlJvb21JZCI6ImlyXzU1NTd5bDVoIiwiU3RyZWFtSWQiOiJpcl81NTU3eWw1aF8xNzEwMl9hZ2VudCIsIkVuY29kZUNvZGUiOiJIMjY0IiwiQ29uZmlnSWQiOiJ3ZWIifV19"
  }
}