智能体列表

接口说明

分页查询可用的智能体列表，支持按性别筛选和类型过滤（官方角色 / 自定义角色 / 全部）。

基本信息

项目	说明
接口路径	POST /v1/agent/list
响应类型	application/json
认证方式	API Key + 请求签名（认证说明）

请求体

{
  "pageNumber": 1,
  "pageSize": 20,
  "language": "en",
  "gender": "female",
  "type": "official"
}

字段	类型	必填	说明
pageNumber	number	✅	页码，从 1 开始
pageSize	number	✅	每页条数，最小 1
language	string	✅	语言代码，如 en、zh、ja
gender	string	❌	性别筛选：male 或 female；不传则返回全部
type	string	❌	角色类型：见下方说明；默认 official

type 参数说明

type	说明
official（默认）	仅返回官方角色
custom	仅返回当前 API Key 创建的自定义角色
all	官方角色 + 当前 API Key 的自定义角色

响应格式

成功响应

{
  "code": 10200,
  "success": true,
  "message": "OK",
  "data": {
    "total": 42,
    "pageNumber": 1,
    "pageSize": 20,
    "items": [
      {
        "id": "a36b6b38-e94d-ad19-c170-ad8de3a1a018",
        "name": "Mia",
        "cover": "https://cdn.example.com/agent/cover/uuid.png",
        "description": "A cheerful and outgoing girl who loves photography.",
        "introduction": "Hi! I'm Mia. Let's chat!",
        "label": ["Friendly", "Creative"],
        "gender": "female",
        "rank": 1
      }
    ]
  },
  "traceId": "xEo3sQwB6KRuwFfG2BxNWwlLQhKrvg38",
  "timestamp": "1773298769366"
}

data 字段

字段	类型	说明
total	number	总条数
pageNumber	number	当前页码
pageSize	number	每页条数
items	AgentInfo[]	智能体列表

AgentInfo 字段

字段	类型	说明
id	string	智能体 ID，用于创建会话
name	string	智能体名称（当前语言）
cover	string	封面图 URL
description	string	简介描述
introduction	string	开场白
label	string[]	标签列表
gender	string	性别：male / female
rank	number	排序权重

错误响应

HTTP 状态码	说明
401	鉴权失败（缺少请求头、时间戳过期、API Key 无效或签名错误）
200	参数校验失败等业务错误：success=false，code=10400，message 为具体原因

客户端示例

async function fetchAgentList(apiKey, apiSecret, userId, { pageNumber = 1, pageSize = 20, language = 'en', gender, type } = {}) {
  const body = { pageNumber, pageSize, language }
  if (gender) body.gender = gender
  if (type) body.type = type

  const headers = await buildAuthHeaders(apiKey, apiSecret, userId, body, {
    url: '/v1/agent/list',
  })

  const response = await fetch('/v1/agent/list', {
    method: 'POST',
    headers,
    body: JSON.stringify(body),
  })

  const result = await response.json()
  if (!result.success) throw new Error(result.message)
  return result.data // { items, total, pageNumber, pageSize }
}

// 获取官方女性角色（第 1 页）
const { items } = await fetchAgentList(apiKey, apiSecret, userId, {
  language: 'en',
  gender: 'female',
  type: 'official',
})

// 获取当前账号的自定义角色
const { items: myAgents } = await fetchAgentList(apiKey, apiSecret, userId, {
  language: 'en',
  type: 'custom',
})