搜索角色卡 · Search Character Cards

按关键词搜索平台上的公开角色卡，支持分页。搜索结果综合文本相关性与角色热度排序，常用于搜索页、联想推荐等场景。

接口地址

POST https://xiangcao.ai/api/search-character-cards

普通（非流式）接口，走 /api 前缀。

鉴权

这是公开接口，鉴权可选：

• 不带 Token 也能调用。
• 携带 Token 时会按用户做调用频率限制（rate limit）：

Authorization: Bearer <YOUR_API_KEY>

请求体（JSON）

分页说明

• 每页最多返回 20 条结果。
• cursor / nextCursor 为偏移量（从 0 开始的整数，字符串形式），与其他列表接口的 base64 游标不同。
• 首次请求相当于 cursor: "0"（或不传 cursor）。

类型定义（TypeScript）

interface SearchCharacterCardsRequest {
  /** 搜索关键词 */
  query: string;
  /** 分页偏移量；首次不传，翻页传上一页的 nextCursor */
  cursor?: string;
}

type SearchCharacterCardsResponse = PaginatedResponse<CharacterCard>;

响应（JSON）

返回标准分页结构：items 为本页角色卡数组，nextCursor 为下一页偏移量（为 null 表示已到末页）。

CharacterCard 结构与 获取公开角色卡列表 相同。列表项通常已足够渲染搜索结果卡片；需要完整设定时请用 id 调用 get-public-character-card。

响应示例：

{
  "items": [
    {
      "id": "abc123",
      "data": {
        "name": "小狐狸",
        "description": "一只喜欢冒险的小狐狸……",
        "avatarUrl": "https://cdn.xiangcao.ai/avatars/abc123.png",
        "tags": ["冒险", "治愈"]
      },
      "status": "public",
      "popularity": 12500,
      "popularityTier": 2,
      "createdBy": "user_001",
      "createdAt": 1700000000000
    }
  ],
  "nextCursor": "20"
}

示例

首次搜索：

curl -X POST "https://xiangcao.ai/api/search-character-cards" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "狐狸"
  }'

翻页：

curl -X POST "https://xiangcao.ai/api/search-character-cards" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "狐狸",
    "cursor": "20"
  }'

错误处理

出错时返回相应 HTTP 状态码及 JSON。