直播列表

基本信息

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

请求体

{
  "pageNumber": 1,
  "pageSize": 20,
  "gender": "female"
}

字段	类型	必填	说明
pageNumber	number	✅	页码，从 1 开始
pageSize	number	✅	每页条数，最小为 1
gender	string	❌	性别筛选：male（男）、female（女），不传则返回全部

响应格式

成功响应

{
  "code": 10200,
  "success": true,
  "message": "OK",
  "data": {
    "items": [
      {
        "id": "123",
        "cover": "https://cdn.example.com/cover.jpg",
        "agent_id": "agent-uuid",
        "agent_name": "Aria",
        "gender": "female",
        "rank": 1
      }
    ],
    "total": 100,
    "pageNumber": 1,
    "pageSize": 20
  },
  "traceId": "9fU0kfWy3E8YFGjS5S8bLPlAXG8xhdTH",
  "timestamp": "1773298769366"
}

字段	类型	说明
data.items	array	当前页直播列表
data.items[].id	string	直播 ID
data.items[].cover	string	封面图 URL
data.items[].agent_id	string	角色 ID
data.items[].agent_name	string	角色名称
data.items[].gender	string	性别：male / female / unknown
data.items[].rank	number	排序权重，数值越小越靠前
data.total	number	符合条件的总条数
data.pageNumber	number	当前页码
data.pageSize	number	每页条数

错误响应

HTTP 状态码	说明
401	认证失败
400	请求参数缺失或格式错误
500	服务内部错误

客户端示例

async function getLiveList(apiKey, apiSecret, userId, pageNumber = 1, pageSize = 20, gender = null) {
  const body = { pageNumber, pageSize }
  if (gender) body.gender = gender

  const headers = await buildAuthHeaders(apiKey, apiSecret, userId, body)
  const response = await fetch('/v1/live/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 }
}