获取公开角色卡列表 · List Public Character Cards

分页拉取平台上的公开角色卡，可按热度/时间排序、按作者筛选，也支持「男性角色」专属榜单。常用于「角色广场」「作者主页公开作品」等列表场景。

接口地址

POST https://xiangcao.ai/api/list-public-character-cards

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

鉴权

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

• 不带 Token 也能调用，返回公开（status: "public" 且审核通过）的角色卡。
• 携带 Token 时会按用户做调用频率限制（rate limit）：

Authorization: Bearer <YOUR_API_KEY>

请求体（JSON）

所有字段均为可选。首次请求通常只需传 sortBy（或什么都不传，用默认排序）；翻页时把上一页响应里的 nextCursor 回传给 cursor 即可。

排序模式 sortBy

完整类型定义（TypeScript）

interface ListPublicCharacterCardsRequest {
  /** 分页游标；首次请求不传，后续传上一页的 nextCursor */
  cursor?: string;
  /** 指定用户 ID 时只返回该用户创建的公开角色卡 */
  userId?: string;
  /** 排序模式，默认 "popular" */
  sortBy?: CharacterCardSortMode;
}

type CharacterCardSortMode =
  | "popular"
  | "newest"
  | "trending"
  | "weekly"
  | "monthly"
  | "quarterly"
  | "male"; // 男性角色榜：过滤 data.gender == "male" 后按热度排序

响应（JSON）

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

interface PaginatedResponse<T> {
  /** 本页数据列表 */
  items: T[];
  /** 下一页游标；为 null 时表示没有更多数据 */
  nextCursor: string | null;
}

// 实际响应类型
type ListPublicCharacterCardsResponse = PaginatedResponse<CharacterCard>;

角色卡对象 CharacterCard

items 中的每一项结构如下（仅列常用字段；统计类字段由服务端计算，调用方只读）：

interface CharacterCard {
  /** 角色卡文档 ID（用于后续 get-public-character-card / 发起对话的 characterId） */
  id?: string;
  /** 角色卡核心数据（名称、描述、头像等） */
  data: CharacterCardData;

  /** 状态：public（公开）/ private（私密） */
  status?: "private" | "public";
  /** 是否为官方角色卡 */
  isOfficial?: boolean;
  /** 是否匿名发布 */
  isAnonymous?: boolean;
  /** 封面图是否为 NSFW */
  isAvatarNsfw?: boolean;

  /** 热度值 */
  popularity?: number;
  /** 热度等级 0-4（用于前端展示边框/角标） */
  popularityTier?: 0 | 1 | 2 | 3 | 4;
  /** 近期热门分数 */
  trendingScore?: number;

  /** 来源：original / workshop / remix / imported */
  source?: "original" | "workshop" | "remix" | "imported";
  /** 创建者用户 ID */
  createdBy?: string;
  /** 创建时间戳（毫秒） */
  createdAt?: number;
  /** 更新时间戳（毫秒） */
  updatedAt?: number;
}

interface CharacterCardData {
  /** 角色名称 */
  name?: string;
  /** 昵称（展示时可替代 name） */
  nickname?: string;
  /** 角色描述 */
  description?: string;
  /** 头像 URL */
  avatarUrl?: string;
  /** 立绘（海报）URL */
  posterUrl?: string;
  /** 角色性别 */
  gender?: "male" | "female" | "other";
  /** 标签 */
  tags?: string[];
  /** 创作者名 */
  creator?: string;
  // …其余 SillyTavern V2/V3 标准字段
}

列表接口返回的是角色卡概要，列表里的 data 通常已足够渲染卡片。需要完整设定（first_mes、世界书等）时，用列表项的 id 调用 get-public-character-card。

分页用法

1. 首次请求不传 cursor，拿到第一页 items 与 nextCursor。
2. 若 nextCursor 不为 null，把它作为下次请求的 cursor 继续拉取。
3. 直到某次响应的 nextCursor 为 null，说明已到末页。

示例

请求第一页（按热度）：

curl -X POST "https://xiangcao.ai/api/list-public-character-cards" \
  -H "Content-Type: application/json" \
  -d '{
    "sortBy": "popular"
  }'

响应（节选）：

{
  "items": [
    {
      "id": "card_abc123",
      "status": "public",
      "popularity": 128400,
      "popularityTier": 4,
      "createdBy": "user_001",
      "createdAt": 1733900000000,
      "data": {
        "name": "苏晚",
        "description": "都市悬疑里的冷面侦探……",
        "avatarUrl": "https://cdn.example.com/avatars/abc123.png",
        "gender": "male",
        "tags": ["悬疑", "都市"],
        "creator": "夜航"
      }
    }
  ],
  "nextCursor": "eyJ2IjoxMjg0MDAsInAiOjF9"
}

请求下一页（回传上一页的 nextCursor）：

curl -X POST "https://xiangcao.ai/api/list-public-character-cards" \
  -H "Content-Type: application/json" \
  -d '{
    "sortBy": "popular",
    "cursor": "eyJ2IjoxMjg0MDAsInAiOjF9"
  }'

只看某位作者的公开作品：

curl -X POST "https://xiangcao.ai/api/list-public-character-cards" \
  -H "Content-Type: application/json" \
  -d '{ "userId": "user_001", "sortBy": "newest" }'

只看男性角色榜：

curl -X POST "https://xiangcao.ai/api/list-public-character-cards" \
  -H "Content-Type: application/json" \
  -d '{ "sortBy": "male" }'

错误处理

出错时返回相应 HTTP 状态码及 JSON：{ "error": "..." }。