ListAgents

POST

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

By calling this API, you can obtain a list of available AI agents.

Request

Query Parameters

Action stringrequired

Possible values: [ListAgents]

API Prototype Parameter

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

AppId uint32required

The unique Application ID assigned to your project by ZEGOCLOUD. Get it from the ZEGOCLOUD Admin Console.

SignatureNonce stringrequired

Random string.

Timestamp int64required

Unix timestamp, in seconds. The maximum allowed error is 10 minutes.

Signature stringrequired

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]

Signature version number, default value is 2.0.

application/json

Body

required

Limit integer

Possible values: >= 0 and <= 10

Default value: 5

The number of AI agent information entries to retrieve in one request. The value range is [0, 10]. If not filled or the value is 0, it defaults to 5. If the value is less than 0 or greater than 10, the API request will return an error.

Cursor string

Pagination retrieval marker. Leave blank for the first request, then fill in the Cursor value returned from the previous response. When the returned Cursor is empty, it indicates that the list of AI agents has been fully retrieved.

Responses

Success

application/json

Schema
Example (from schema)
Example

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

Total integer

Total number of AI agents that meet the query criteria

Agents object[]

AI Agent list

Array[

AgentId string

AI agent unique identifier

Name string

AI agent name

LLM object

Url stringrequired

The endpoint that receives the request (can be your own service or any LLM service provider's service) and must be compatible with OpenAI Chat Completions API.

For example: https://api.openai.com/v1/chat/completions

📌 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 in the request parameters when requesting the LLM service. 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

TTS object

Vendor stringrequired

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

The TTS service provider. Options:

Aliyun: Aliyun
ByteDance: ByteDance (Volcano Voice - Large Model Speech Synthesis API)
ByteDanceFlowing: ByteDance (Volcano Voice - Streaming Speech Synthesis API (WebSocket))
MiniMax: MiniMax
CosyVoice: Aliyun CosyVoice

Params objectrequired

TTS configuration parameters, in JSON object format. Contains app parameters (for authentication) and other parameters (for adjusting TTS effects).

In addition to the app parameter, you can also pass in other TTS configuration parameters to adjust the speech synthesis effect. These parameters will be directly passed to the corresponding TTS service provider.

You can refer to the official documentation of the service provider for the required information according to the value of Vendor.

- Aliyun: Intelligent Speech Interaction - Overview of speech synthesis - 2. Start the synthesis task

- ByteDance: Large Model Speech Synthesis API - Parameter List - Request Parameters

- ByteDanceFlowing: "Payload request parameters" in Streaming Text-to-Speech API (WebSocket) - WebSocket Binary Protocol

- MiniMax: Voice Model - T2A v2 - WebSocket API - Interface Parameters

- CosyVoice: "Payload request parameters" in CosyVoice WebSocket API for Speech Synthesis

app object required

The TTS service authentication parameter, which is different for different Vendor values. Please refer to the requirements of each vendor for the structure of the app parameter.

oneOf

Aliyun
ByteDance
ByteDanceFlowing
MiniMax
CosyVoice

app_key stringrequired

Read the Alibaba Cloud docs Intelligent Speech Interaction - Create a project to create a project and get the AppKey from the Intelligent Speech Interaction console, and pass it here.

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

ak_id stringrequired

Read the Alibaba Cloud docs Intelligent Speech Interaction - Activate Intelligent Speech Interaction - Procedure to obtain the AccessKey ID and pass it here.

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

ak_key stringrequired

Read the Alibaba Cloud docs Intelligent Speech Interaction - Activate Intelligent Speech Interaction - Procedure to obtain the AccessKey Secret and pass it here.

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

appid stringrequired

Read the BytePlus docs Voice Technology - Quick Start - Console Usage FAQ under "Where can I get the following parameters: appid, cluster, token, authorization_type, secret_key?".

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

token stringrequired

Read the BytePlus docs Voice Technology - Quick Start - Console Usage FAQ under "Where can I get the following parameters: appid, cluster, token, authorization_type, secret_key?".

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

cluster required

Possible values: [volcano_tts, volcano_mega, volcano_icl]

Default value: volcano_tts

BytePlus cluster configuration

📌 Important Note

This parameter must match the audio.voice_type parameter.

appid stringrequired

Read the BytePlus Voice docs Voice Console Guide - Step 2: Trial Use to get the App ID, and pass it here.

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

token stringrequired

Read the BytePlus Voice docs Voice Console Guide - Step 2: Trial Use to get the App ID, and pass it here.

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

resource_id required

Possible values: [volc.service_type.10029, volc.megatts.default, volc.megatts.concurr]

Default value: volc.service_type.10029

BytePlus resource ID

📌 Important Note

This parameter must match the req_params.speaker parameter.

other_params string

📌 Important Note

other_params is not a valid parameter, it is only used to demonstrate how to pass vendor parameters. Except for the app parameter, other parameters are directly passed to the vendor parameters.

The following are the parameter filling examples for each vendor, please fill in according to your actual needs:

Aliyun:

"TTS": {
    "Vendor": "Aliyun",
    "Params": {
        "app":{
            "app_key": "your key",
            "ak_id": "your ak id",
            "ak_key": "your ak key"
        },
        "voice": "zhitian_emo"
    }
}

"TTS": {
    "Vendor": "Aliyun",
    "Params": {
        "app":{
            "app_key": "your key",
            "ak_id": "your ak id",
            "ak_key": "your ak key"
        },
        "voice": "zhitian_emo"
    }
}

ByteDance:

/*
    cluster configuration description: 
    default: volcano_tts: normal voice cluster
          volcano_mega: voice clone large model 1.0
          volcano_icl: voice clone large model 2.0
*/

"TTS": {
    "Vendor": "ByteDance",
    "Params": {
        "app": {
            "appid": "your_appid",
            "token": "your_token",
            "cluster": "volcano_tts"
        },
        "audio": {
            "voice_type": "your_voice_type"
        }
    }
}

/*
    cluster configuration description: 
    default: volcano_tts: normal voice cluster
          volcano_mega: voice clone large model 1.0
          volcano_icl: voice clone large model 2.0
*/

"TTS": {
    "Vendor": "ByteDance",
    "Params": {
        "app": {
            "appid": "your_appid",
            "token": "your_token",
            "cluster": "volcano_tts"
        },
        "audio": {
            "voice_type": "your_voice_type"
        }
    }
}

ByteDanceFlowing:

/*
    resource_id configuration description: 
    default: volc.service_type.10029, that is: Volcano large model speech synthesis
    voice clone 2.0:
       volc.megatts.default（hour version）
       volc.megatts.concurr（concurrent version） 
    ⚠️（voice clone 1.0 is not supported）
    ⚠️Note: speaker (voice id) and resource_id must match
*/

"TTS": {
    "Vendor": "ByteDanceFlowing",
    "Params": {
        "app": {
            "appid": "your appid",
            "token": "your token",
            "resource_id": "volc.service_type.10029" // voice resourceid
        },
        "req_params": {
            "speaker": "zh_female_qingxinnvsheng_mars_bigtts" //voice id
        }
    }
}

/*
    resource_id configuration description: 
    default: volc.service_type.10029, that is: Volcano large model speech synthesis
    voice clone 2.0:
       volc.megatts.default（hour version）
       volc.megatts.concurr（concurrent version） 
    ⚠️（voice clone 1.0 is not supported）
    ⚠️Note: speaker (voice id) and resource_id must match
*/

"TTS": {
    "Vendor": "ByteDanceFlowing",
    "Params": {
        "app": {
            "appid": "your appid",
            "token": "your token",
            "resource_id": "volc.service_type.10029" // voice resourceid
        },
        "req_params": {
            "speaker": "zh_female_qingxinnvsheng_mars_bigtts" //voice id
        }
    }
}

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

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

CosyVoice:

{
    "Vendor": "CosyVoice",
    "Params": {
        "app": {
            "api_key": "your_api_key"
        },
        "payload": {
            "model": "cosyvoice-v2",
            "parameters": {
                "voice": "longxiaochun_v2"
            }
        }
    }
}

{
    "Vendor": "CosyVoice",
    "Params": {
        "app": {
            "api_key": "your_api_key"
        },
        "payload": {
            "model": "cosyvoice-v2",
            "parameters": {
                "voice": "longxiaochun_v2"
            }
        }
    }
}

FilterText object[]

Filter the text within the specified punctuation marks from the content returned by the LLM, and then perform speech synthesis.Note:- The content that should be placed within the specified punctuation marks must be defined in LLM > SystemPrompt.- This parameter cannot be updated when updating the AI 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 of TTS. If the content in the input TTS text matches the TerminatorText string, the content from the TerminatorText string (including) will not be synthesized for this round of TTS.

📌 Important Note

Only one character can be set for bidirectional streaming.

ASR object

HotWord string

The hot word list is used to improve the recognition accuracy. Format: Hotword1|Weight1,Hotword2|Weight2,Hotword3|Weight3

A single hot word cannot exceed 30 characters, cannot contain spaces, and the weight range is [-1, 11]. Up to 128 hot words are supported.

📌 Important Note

When the weight is 11, it means that the word is a super hot word. It is recommended to set only the important and must-take-effect hot words to 11, and too many hot words with a weight of 11 will affect the recognition effect.

Params object

Extended parameters, please contact ZEGOCLOUD technical support for details.

VADSilenceSegmentation number

Possible values: >= 200 and <= 2000

Default value: 500

Set the time after which the user's speech is no longer considered as a sentence. The unit is ms, range [200, 2000], default is 500.

PauseInterval number

Possible values: >= 200 and <= 2000

Set the time within which two sentences are considered as one sentence, i.e., ASR multi-sentence concatenation. The unit is ms, range [200, 2000]. Only when this value is greater than VADSilenceSegmentation, ASR multi-sentence concatenation will be enabled.

]

Cursor string

A non-empty value only indicates that there are still AI agent details not returned, and you need to set this field in the request parameter Cursor to fetch more AI agent information; an empty value indicates that all AI agent information has been returned.

{
  "Code": 0,
  "Message": "Success",
  "RequestId": "8825223157230377926",
  "Data": {
    "Total": 10,
    "Agents": [
      {
        "AgentId": "Jacky",
        "Name": "Jacky",
        "LLM": {
          "Url": "https://ark.cn-beijing.volces.com/api/v3/chat/completions",
          "ApiKey": "zego_test",
          "Model": "doubao-1-5-lite-32k-250115",
          "SystemPrompt": "You are a friendly assistant",
          "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": {
          "HotWord": "ZEGO|10,AI|10,Agent|10",
          "Params": {},
          "VADSilenceSegmentation": 500,
          "PauseInterval": 800
        }
      }
    ],
    "Cursor": "COAI"
  }
}

{
  "Code": 0,
  "Message": "Success",
  "RequestId": "8825223157230377926",
  "Data": {
    "Total": 10,
    "Agents": [
      {
        "AgentId": "Jacky",
        "Name": "Jacky",
        "LLM": {
          "Url": "https://ark.cn-beijing.volces.com/api/v3/chat/completions",
          "ApiKey": "zego_test",
          "Model": "doubao-1-5-lite-32k-250115",
          "SystemPrompt": "You are a friendly assistant",
          "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": {
          "HotWord": "ZEGO|10,AI|10,Agent|10",
          "Params": {},
          "VADSilenceSegmentation": 500,
          "PauseInterval": 800
        }
      }
    ],
    "Cursor": "COAI"
  }
}

{
  "Code": 0,
  "Message": "Success",
  "RequestId": "8825223157230377926",
  "Data": {
    "Total": 10,
    "Agents": [
      {
        "AgentId": "Jacky",
        "Name": "Jacky",
        "LLM": {
          "Url": "https://ark.cn-beijing.volces.com/api/v3/chat/completions",
          "ApiKey": "eexxxxxxxxxxxxxxx",
          "Model": "ep-xxxxxxxxxx",
          "SystemPrompt": "You are Jacky, an adult man, a companion assistant **created by ZEGOCLOUD**. knowledgeable in everything, intelligent, wise, enthusiastic, and friendly. \nDialogue requirements: 1. Dialogue with users according to the requirements of the persona. \n2.No more than 100 words."
        },
        "TTS": {
          "Vendor": "ByteDance",
          "Params": {
            "app": {
              "appid": "your_appid",
              "cluster": "volcano_tts",
              "token": "your_token"
            },
            "audio": {
              "voice_type": "your_voice_type"
            }
          }
        },
        "ASR": {}
      }
    ],
    "Cursor": "COAI"
  }
}

{
  "Code": 0,
  "Message": "Success",
  "RequestId": "8825223157230377926",
  "Data": {
    "Total": 10,
    "Agents": [
      {
        "AgentId": "Jacky",
        "Name": "Jacky",
        "LLM": {
          "Url": "https://ark.cn-beijing.volces.com/api/v3/chat/completions",
          "ApiKey": "eexxxxxxxxxxxxxxx",
          "Model": "ep-xxxxxxxxxx",
          "SystemPrompt": "You are Jacky, an adult man, a companion assistant **created by ZEGOCLOUD**. knowledgeable in everything, intelligent, wise, enthusiastic, and friendly. \nDialogue requirements: 1. Dialogue with users according to the requirements of the persona. \n2.No more than 100 words."
        },
        "TTS": {
          "Vendor": "ByteDance",
          "Params": {
            "app": {
              "appid": "your_appid",
              "cluster": "volcano_tts",
              "token": "your_token"
            },
            "audio": {
              "voice_type": "your_voice_type"
            }
          }
        },
        "ASR": {}
      }
    ],
    "Cursor": "COAI"
  }
}

CURL

RESPONSEClear

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

ListAgents

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

Request

Query Parameters

Body

Responses​

Responses