logo
当前页

CreateDigitalHumanAgentInstance

POST

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

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

注意

如果 RTC 房间 120 秒后没有真实用户存在,则智能体实例会自动销毁,并触发 Event 为 AgentInstanceDeleted 回调,Data.Code 为 1202。

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。

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)服务提供商。选项:

    • Aliyun: 阿里云
    • ByteDance: 字节跳动火山语音(大模型语音合成 API)
    • ByteDanceFlowing: 字节跳动火山语音(流式语音合成 API (WebSocket))
    • MiniMax: MiniMax
    • CosyVoice: 阿里云 CosyVoice
    Params objectrequired

    TTS 配置参数,格式为 JSON 对象。包含 app 参数(用于认证)和其他参数(用于调整 TTS 效果)。


    除 app 参数外,还可以传入其他 TTS 配置参数来调整语音合成效果,这些参数会直接透传给对应的 TTS 服务提供商。

    您可以根据 Vendor 的值,参考如下服务提供商的官方文档获取所需信息:

    - Aliyun:智能语音合成 - 接口说明

    - ByteDance:大模型语音合成 API - 参数列表 - 请求参数

    - ByteDanceFlowing:双向流式 API - WebSocket 二进制协议 中的 “Payload 请求参数”

    - MiniMax:语音模型 - T2A v2 - WebSocket - 接口请求参数

    - CosyVoice:语音合成CosyVoice WebSocket API 中的 “payload 请求参数”

    app object required
    用于 TTS 服务鉴权,不同的 Vendor 值要求传入的 app 参数的结构不同,请查看一下每个厂商的要求说明。
    oneOf
    app_key stringrequired

    请参考阿里云文档 智能语音交互 - 快速入门 - 从这里开始 中 “步骤 4:管理项目” 获取 AppKey 并传入此处。

    📌 重要说明

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

    ak_id stringrequired

    请参考阿里云文档 智能语音交互 - 快速入门 - 从这里开始 中 “步骤 2:创建 AccessKey” 获取 AccessKey ID 并传入此处。

    📌 重要说明

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

    ak_key stringrequired

    请参考阿里云文档 智能语音交互 - 快速入门 - 从这里开始 中 “步骤 2:创建 AccessKey” 获取 AccessKey Secret 并传入此处。

    📌 重要说明

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

    other_params string

    📌 重要说明

    other_params 不是一个有效参数,仅仅是为了说明如何透传厂商参数。 除 app 参数外,其余参数均直接透传厂商参数。

    以下是各家厂商的参数填写示例,请根据实际需求填写:

    1. Aliyun:
    "TTS": {
        "Vendor": "Aliyun",
        "Params": {
            "app":{
                "app_key": "your key",
                "ak_id": "your ak id",
                "ak_key": "your ak key"
            },
            "voice": "zhitian_emo"
        }
    }
    
    1
    Copied!
    1. ByteDance:
    /*
        cluster 配置说明: 
        默认 :volcano_tts:普通音色的集群
              volcano_mega: 声音复刻大模型 1.0
              volcano_icl:声音复刻大模型 2.0
    */
    
    "TTS": {
        "Vendor": "ByteDance",
        "Params": {
            "app": {
                "appid": "your_appid",
                "token": "your_token",
                "cluster": "volcano_tts"
            },
            "audio": {
                "voice_type": "your_voice_type"
            }
        }
    }
    
    1
    Copied!
    1. ByteDanceFlowing:
    /*
        resource_id 配置说明: 
        默认 :volc.service_type.10029, 即:火山大模型语音合成
        声音复刻2.0:
           volc.megatts.default(小时版)
           volc.megatts.concurr(并发版) 
        ⚠️(不支持声音复刻1.0)
        ⚠️注意:speaker(音色id)和resource_id 要匹配
    */
    
    "TTS": {
        "Vendor": "ByteDanceFlowing",
        "Params": {
            "app": {
                "appid": "your appid",
                "token": "your token",
                "resource_id": "volc.service_type.10029" // 音色resourceid
            },
            "req_params": {
                "speaker": "zh_female_qingxinnvsheng_mars_bigtts" //音色id
            }
        }
    }
    
    1
    Copied!
    1. Minimax:
    "TTS": {
        "Vendor": "MiniMax",
        "Params": {
            "app": {
                "group_id": "your_group_id",
                "api_key":  "your_api_key",
            },
            "model": "speech-02-turbo-preview",
            "voice_setting": {
                "voice_id": "male-qn-qingse"
            }
        }
    }
    
    1
    Copied!
    1. CosyVoice:
    {
        "Vendor": "CosyVoice",
        "Params": {
            "app": {
                "api_key": "your_api_key"
            },
            "payload": {
                "model": "cosyvoice-v2",
                "parameters": {
                    "voice": "longxiaochun_v2"
                }
            }
        }
    }
    
    1
    Copied!
    FilterText object[]
    从 LLM 返回的内容中过滤指定标点符号内的文本,然后再进行语音合成。注意:- 需要在 LLM > SystemPrompt 中定义哪些内容应该放在指定标点符号内- 此参数在更新智能体实例时无法更新
  • Array[
  • BeginCharacters stringrequired

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

    EndCharacters stringrequired

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

  • ]
  • ASR object
    HotWord string

    热词列表用于提高识别准确率。格式:Hotword1|Weight1,Hotword2|Weight2,Hotword3|Weight3

    单个热词不超过 30 个字符(最多 10 个汉字),不能包含空格,权重范围:[-1, 11]。 最多支持 128 个热词

    📌 重要说明

    当权重为 11 时,表示该词为超级热词。建议仅将重要且必须生效的热词设置到 11,过多权重为 11 的热词会影响识别效果。

    Params object

    扩展参数,详情请联系 ZEGO 技术支持。

    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 多句拼接。

    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 integer

    Possible values: >= 0 and <= 100

    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 <= 100

    创建智能体实例时,从 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

创建成功
Schema
    Code integer

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

    Message string

    请求结果说明

    RequestId string

    请求 ID

    Data object
    AgentInstanceId string

    智能体实例的唯一标识。

    DigitalHumanConfig string

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


1
Copied!
Request
Collapse all
Base URL
https://aigc-aiagent-api.zegotech.cn
统一接入地址(不区分区域)
Parameters
queryrequired
queryrequired
queryrequired
queryrequired
queryrequired
queryrequired
Bodyrequired
{
"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": ")"
}
]
},
"ASR": {
"HotWord": "历史类|10,物理类|10,体育类|10",
"Params": {},
"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!

Previous

创建语音智能体实例

Next

修改智能体实例

当前页

返回到顶部