CreateDigitalHumanAgentInstance

POST

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

通过本接口，您可以创建数字人智能体实例，并将智能体实例加入到语音（RTC）对话之中。

注意

如果 RTC 房间 120 秒后没有真实用户存在，则智能体实例会自动销毁，并触发 Event 为 AgentInstanceDeleted 回调，Data.Code 为 1202。
默认情况下一个账号下最多同时存在 10 个数字人智能体实例，超过限制后创建数字人智能体实例会失败，如需调整请联系 ZEGO 商务。

Request

Query Parameters

Action stringrequired

Possible values: [CreateDigitalHumanAgentInstance]

接口原型参数

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

AppId uint32required

AppId，ZEGO 分配的用户唯一凭证。

SignatureNonce stringrequired

随机字符串。

Timestamp int64required

Unix 时间戳，单位为秒。最多允许 10 分钟的误差。

Signature stringrequired

签名，用于验证请求的合法性。

SignatureVersion stringrequired

Possible values: [2.0]

签名版本号，默认值为 2.0。

application/json

Body

required

AgentId stringrequired

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

UserId stringrequired

Possible values: <= 32 characters

用于登录 RTC 房间的真实用户 ID。仅支持数字、英文字符、'-'、'_'。

RTC objectrequired

RTC 相关信息

📌 重要说明

所有属性字符限制：仅支持数字、英文字符、'_'、'-'、'.'。

RoomId stringrequired

Possible values: <= 128 characters

RTC 房间 ID。

AgentStreamId stringrequired

Possible values: <= 128 characters

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

📌 重要说明

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

AgentUserId stringrequired

Possible values: <= 32 characters

智能体实例的用户 ID。

📌 重要说明

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

UserStreamId stringrequired

Possible values: <= 128 characters

真实用户推流使用的流 ID。

LLM object

Url stringrequired

接收请求的端点（可以是你自己的服务，也可以是任何 LLM 服务提供商提供的服务），并且必须兼容 OpenAI Chat Completions API。

例如：https://api.openai.com/v1/chat/completions

📌 重要说明

如果 ApiKey 设置为 "zego_test"，则必须使用以下 Url 地址之一：

MiniMax：https://api.minimax.chat/v1/text/chatcompletion_v2

火山引擎（豆包）：https://ark.cn-beijing.volces.com/api/v3/chat/completions

阿里云百炼（通义千问）：https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions

阶跃星辰：https://api.stepfun.com/v1/chat/completions

ApiKey string

LLM 服务提供商用于认证的参数。默认为空，但在生产环境中必须提供。

📌 重要说明

在接入测试期间(AI Agent 服务开通 2 周内)，可以将该参数值设置为 "zego_test" 即可使用该服务。

Model stringrequired

LLM 模型。不同的 LLM 服务提供商支持不同的模型，请参考其官方文档选择合适的模型。

📌 重要说明

如果 ApiKey 设置为 "zego_test"，则必须使用以下模型之一：

MiniMax：

MiniMax-Text-01

火山引擎（豆包）：

doubao-1-5-pro-32k-250115

doubao-1-5-lite-32k-250115

阿里云百炼（通义千问）：

qwen-plus

阶跃星辰：

step-2-16k

SystemPrompt string

智能体系统提示（prompt）。调用 LLM 时附加在最前的预定义信息，用于控制 LLM 输出。可以是角色设定、提示词和回答样例等。

Temperature number

Possible values: >= 0 and <= 2

Default value: 0.7

数值越高，输出越随机；数值越低，输出越集中和确定。

TopP number

Possible values: >= 0 and <= 1

Default value: 0.9

采样方法，数值越小，确定性越强；数值越大，随机性越强。

Params object

LLM 服务提供商支持的其他参数，如最大 Token 数量限制等。不同的 LLM 提供商支持不同的参数，请参考其官方文档并根据需要填写。

AddAgentInfo boolean

Default value: false

如果此值为 true，AI Agent 服务器在请求 LLM 服务时会在请求参数中包含智能体信息。您可以使用此参数在自定义 LLM 服务中执行额外的业务逻辑。

agent_info 的结构如下：

room_id: 房间 ID
user_id: 用户 ID
agent_instance_id: 智能体实例 ID

TTS object

Vendor stringrequired

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

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

Params objectrequired

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

app objectrequired

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

other_params string

📌 重要说明

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

FilterText object[]

从 LLM 返回的内容中过滤指定标点符号内的文本，然后再进行语音合成。注意：- 需要在 LLM > SystemPrompt 中定义哪些内容应该放在指定标点符号内- 此参数在更新智能体实例时无法更新

Array[

BeginCharacters stringrequired

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

EndCharacters stringrequired

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

]

TerminatorText string

Possible values: <= 4 characters

可用于设置 TTS 的终止文本。若输入 TTS 的文本中出现匹配 TerminatorText 字符串的内容，则本轮 TTS 从 TerminatorText 字符串（包含）开始的内容将不再进行语音合成。

📌 重要说明

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

ASR object

Vendor string

Possible values: [Tencent, AliyunParaformer, AliyunGummy, Microsoft]

Default value: Tencent

ASR 厂商。可参考配置 ASR 参数说明。

Params object

厂商参数，具体使用方式参考配置 ASR 中的 Params 参数说明。

VADSilenceSegmentation number

Possible values: >= 200 and <= 2000

Default value: 500

用于设置用户说话停顿多少秒后，不再将两句话视为一句。单位为 ms，范围 [200，2000]，默认为 500。详细说明请参考语音识别断句。

PauseInterval number

Possible values: >= 200 and <= 2000

用于设置用户说话停顿多少秒内，将两句话视为一句，即 ASR 多句拼接。单位为 ms，范围 [200，2000]。仅当此值大于 VADSilenceSegmentation 时，才会启用 ASR 多句拼接。详细说明请参考语音识别断句。

HotWord stringdeprecated

该参数已废弃。请通过 Params 厂商参数设置。

MessageHistory object

供智能体实例使用的历史消息的配置

SyncMode integer

Possible values: [0, 1]

Default value: 0

消息同步模式：

0: 从即时通讯 (ZIM) 同步
1: 通过 Messages 参数同步

Messages object[]

Possible values: <= 100

消息列表

Array[

Role stringrequired

Possible values: [user, assistant]

消息发送者的角色

user: 用户
assistant: 智能体

Content stringrequired

消息内容

]

WindowSize Int

Possible values: >= 0 and <= 200

Default value: 20

每次调用 LLM 服务时使用的近期历史消息数量。影响 LLM 上下文理解能力，建议设置为 10-30。

ZIM object

ZIM 相关信息。

📌 重要说明

- 仅当 MessageHistory.SyncMode 为 0 时有效。

- 请确保您的项目已开通 ZIM 服务。

- 请确保已调用 ZIM 机器人注册接口，并将返回的 UserInfo.UserId 作为 RobotId。

- 建议您提前注册机器人，以便完善用户信息设置并提升智能体实例的创建效率。

RobotId string

ZIM 机器人 ID。即调用 ZIM 注册机器人接口对应的 UserInfo.UserId 。用于加载用户与该 ZIM 机器人的聊天上下文，并将对话过程中产生的消息同步至 ZIM。如果此参数为空，实时互动 AI Agent 后台将随机生成。

LoadMessageCount integer

Possible values: >= 0 and <= 200

创建智能体实例时，从 ZIM 服务获取多少条消息作为上下文。默认为 WindowSize 的值（取值上限）。

CallbackConfig object

服务端回调配置

📌 重要说明

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

ASRResult integer

Possible values: [0, 1]

Default value: 0

是否开启服务端回调 ASR 结果。

LLMResult integer

Possible values: [0, 1]

Default value: 0

是否开启服务端回调 LLM 结果。如果开启，则 ZEGO 服务端将会按照每句话返回 LLM 输出结果。

Interrupted integer

Possible values: [0, 1]

Default value: 0

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

UserSpeakAction integer

Possible values: [0, 1]

Default value: 0

是否开启服务端回调用户说话的回调。

AgentSpeakAction integer

Possible values: [0, 1]

Default value: 0

是否开启服务端回调智能体说话的回调。

UserAudioData integer

Possible values: [0, 1]

Default value: 0

是否开启服务端回调用户说话音频数据。

AdvancedConfig object

InterruptMode integer

Possible values: [0, 1]

Default value: 0

智能体说话时被用户语音打断的模式：

0: 立即打断。如果在 AI 说话时用户说话，那么 AI 将被立刻打断，停止说话。
1: 不打断。如果在 AI 说话时用户说话，那么 AI 不会被影响直到内容说完。

DigitalHuman objectrequired

DigitalHumanId string

数字人形象 ID

ConfigId string

Possible values: [mobile, web]

数字人配置 ID

EncodeCode string

Possible values: [H264, VP8]

Default value: H264

数字人视频编码格式

Responses

创建成功

application/json

Schema
Example (from schema)

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"
  }
}

CURL

Base URL

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

统一接入地址（不区分区域）

Parameters

Actionqueryrequired

AppIdqueryrequired

SignatureNoncequeryrequired

Timestampqueryrequired

Signaturequeryrequired

SignatureVersionqueryrequired

Bodyrequired

Example (from schema)
Example

{
  "AgentId": "xiaozhi",
  "UserId": "user_1",
  "RTC": {
    "RoomId": "room_1",
    "AgentStreamId": "agent_stream_1",
    "AgentUserId": "agent_user_1",
    "UserStreamId": "user_stream_1"
  },
  "LLM": {
    "Url": "https://ark.cn-beijing.volces.com/api/v3/chat/completions",
    "ApiKey": "zego_test",
    "Model": "doubao-1-5-lite-32k-250115",
    "SystemPrompt": "你是一个友好的助手",
    "Temperature": 0.7,
    "TopP": 0.9,
    "Params": {
      "max_tokens": 16384
    },
    "AddAgentInfo": false
  },
  "TTS": {
    "Vendor": "ByteDance",
    "Params": {
      "app": {
        "appid": "zego_test",
        "token": "zego_test",
        "cluster": "volcano_tts"
      },
      "audio": {
        "voice_type": "zh_female_qingxinnvsheng_mars_bigtts",
        "loudness_ratio": 1,
        "speed_ratio": 1
      }
    },
    "FilterText": [
      {
        "BeginCharacters": "(",
        "EndCharacters": ")"
      }
    ],
    "TerminatorText": "string"
  },
  "ASR": {
    "Vendor": "Tencent",
    "Params": {
      "engine_model_type": "16k_en",
      "hotword_list": "zego|10"
    },
    "VADSilenceSegmentation": 500,
    "PauseInterval": 800
  },
  "MessageHistory": {
    "SyncMode": 0,
    "Messages": [
      {
        "Role": "user",
        "Content": "你好，我想了解一下产品信息"
      }
    ],
    "WindowSize": 20,
    "ZIM": {
      "RobotId": "@RBT#robot_123",
      "LoadMessageCount": 20
    }
  },
  "CallbackConfig": {
    "ASRResult": 0,
    "LLMResult": 0,
    "Interrupted": 0,
    "UserSpeakAction": 0,
    "AgentSpeakAction": 0,
    "UserAudioData": 0
  },
  "AdvancedConfig": {
    "InterruptMode": 0
  },
  "DigitalHuman": {
    "DigitalHumanId": "xiaozhi",
    "ConfigId": "mobile",
    "EncodeCode": "H264"
  }
}

RESPONSEClear

Click the "Send" button above and see the response here!

CreateDigitalHumanAgentInstance

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

Request

Query Parameters

Body

Responses​

Responses