UpdateAgentInstance

POST

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

With this interface, you can update the configuration of the AI agent instance.

Warning

You can update the configuration of LLM, TTS, and ASR separately, or update multiple configurations at the same time.
The LLM, TTS, and ASR configuration items are updated in a cover-up manner, meaning that the incoming configuration will overwrite the existing configuration (for example, if you only update LLM.Model, you need to ensure that the other parameters of LLM are set correctly).

Request

Query Parameters

Action stringrequired

Possible values: [UpdateAgentInstance]

API Prototype Parameter

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

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

AgentInstanceId stringrequired

The unique identifier of the AI agent instance, obtained through the response parameters of the Create AI Agent Instance interface.

LLM object

Vendor string

Possible values: [OpenAIChat, OpenAIResponses]

Default value: OpenAIChat

The vendor type of the LLM interface.

OpenAIChat: OpenAI's Chat Completions interface type.
OpenAIResponses: OpenAI's Responses API interface type.

Url stringrequired

The endpoint that receives the request (can be your own service or any LLM service provider's service). If Vendor is OpenAIChat, it must be compatible with OpenAI Chat Completions API. For example: https://api.openai.com/v1/chat/completions

If Vendor is OpenAIResponses, it must be compatible with OpenAI Responses API. For example: https://ark.cn-beijing.volces.com/api/v3/responses

📌 Important Note

If ApiKey is set to "zego_test", you must use one of the following Url addresses:

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

Volcano Engine (Doubao): https://ark.cn-beijing.volces.com/api/v3/chat/completions

Aliyun Bailei (Tongyi Qianwen): https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions

Stepfun: https://api.stepfun.com/v1/chat/completions

ApiKey string

The parameter used for authentication by the LLM service provider. It is empty by default, but must be provided in production environments.

📌 Important Note

During the test period (within 2 weeks after the AI Agent service is enabled), you can set this parameter value to "zego_test" to use this service.

Model stringrequired

The LLM model. Different LLM service providers support different models, please refer to their official documentation to select the appropriate model.

📌 Important Note

If ApiKey is set to "zego_test", you must use one of the following models:

MiniMax:

MiniMax-Text-01

Volcano Engine (Doubao):

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

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

Aliyun Bailei (Tongyi Qianwen):

qwen-plus

Stepfun:

step-2-16k

SystemPrompt string

The system prompt of the AI agent. It is the predefined information that is added at the beginning when calling the LLM, used to control the output of the LLM. It can be role settings, prompts, and answer examples.

Temperature number

Possible values: >= 0 and <= 2

Default value: 0.7

The higher the value, the more random the output; the lower the value, the more concentrated and determined the output.

TopP number

Possible values: >= 0 and <= 1

Default value: 0.9

The sampling method. The smaller the value, the stronger the determinism; the larger the value, the stronger the randomness.

Params object

Other parameters supported by the LLM service provider, such as the maximum token limit. Different LLM providers support different parameters, please refer to their official documentation and fill in as needed.

AddAgentInfo boolean

Default value: false

If this value is true, the AI Agent server will include the AI agent information(agent_info) in the request parameters when requesting the LLM service. The example of the AI agent information is as follows: Using Custom LLM. You can use this parameter to execute additional business logic in your custom LLM service.

The structure of agent_info is as follows:

room_id: RTC room ID
user_id: User ID
agent_instance_id: AI agent instance ID

📌 Important Note: Only effective when Vendor is "OpenAIChat".

AgentExtraInfo object

Agent extra information, the server will pass this parameter in the request parameters when requesting the LLM service. The example of the extra information is as follows: Using Custom LLM.You can use this parameter to execute additional business logic in your custom LLM service.📌 Important Note: Only effective when Vendor is "OpenAIChat".

key string

Extra information key.

value

Extra information value, can be of any type.

TTS object

Vendor stringrequired

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

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

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 > Params 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.

ASR object

Vendor string

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

Default value: Tencent

ASR provider. Please refer to Configuring ASR > ASR Parameters for details.

Params object

Vendor parameters, please refer to Configuring ASR > Params Parameters for details.

VADSilenceSegmentation number

Possible values: >= 200 and <= 2000

Default value: 500

Set the number of seconds after which two sentences are no longer considered as one. Unit is ms, range [200, 2000], default is 500. Please refer to Speech Segmentation Control for details.

📌 Important Note

When Vendor is "Tencent" (default), the maximum value is 1500.

PauseInterval number

Possible values: >= 200 and <= 2000

Set the number of seconds within which two sentences are considered as one, i.e., ASR multi-sentence concatenation. Unit is ms, range [200, 2000]. Only when this value is greater than VADSilenceSegmentation, ASR multi-sentence concatenation will be enabled. Please refer to Speech Segmentation Control for details.

VADSensitiveLevel int

Possible values: [0, 1, 2, 3]

Default value: 0

VAD sensitivity, 0: medium sensitivity, default value; 1: low sensitivity; 2: high sensitivity; 3: custom mode, needs to be used in combination with VADMinSpeechDur and VADEnergyThreshold. Please refer to Voice Interruption Sensitivity Adjustment for details.

VADMinSpeechDur int

Possible values: >= 0 and <= 1000

VAD minimum speech duration, unit ms, the larger the value, the less likely it is to be detected, but it may cause some short speech to be missed, the value range is [0, 1000].

VADEnergyThreshold float

Possible values: >= 0 and <= 1

VAD energy threshold, the smaller the value, the higher the sensitivity, the value range is [0, 1].

HotWord stringdeprecated

This parameter has been deprecated. Please set it through the Params vendor parameters.

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

{
  "Code": 0,
  "Message": "Success",
  "RequestId": "8825223157230377926"
}

{
  "Code": 0,
  "Message": "Success",
  "RequestId": "8825223157230377926"
}