获取角色评论 · List Reviews

分页获取指定角色卡下的评论与回复列表。置顶评论始终排在最前，其余按创建时间倒序。常用于角色详情页的评论区。

接口地址

POST https://xiangcao.ai/api/list-reviews

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

鉴权

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

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

Authorization: Bearer <YOUR_API_KEY>

请求体（JSON）

分页说明

• 首页：最多返回 8 条（置顶评论 + 非置顶评论合计）。
• 翻页：每页最多 20 条非置顶评论；cursor 仅作用于非置顶部分。
• 置顶评论：仅在首页加载，按 pinnedAt 倒序排在列表最前；翻页请求不再返回置顶项。
• 游标格式：nextCursor 为本页最后一条记录的 createdAt 毫秒时间戳（字符串），与其他接口的 base64 游标不同。

类型定义（TypeScript）

interface ListReviewsRequest {
  /** 角色卡 ID */
  characterId: string;
  /** 分页游标；首次请求不传，翻页时传上一页的 nextCursor */
  cursor?: string;
}

interface ListReviewsResponse {
  /** 本页评论列表 */
  items: CharacterReview[];
  /** 下一页游标；为 null 表示已到末页 */
  nextCursor: string | null;
}

interface CharacterReview {
  id?: string;
  characterId: string;
  /** 评论内容（已脱敏） */
  comment: string;
  userId: string;
  userNickname?: string;
  userAvatarUrl?: string;
  userAuthorLevel?: number;
  /** 父评论 ID；存在时表示这是一条回复 */
  parentId?: string | null;
  /** 被引用评论快照（仅回复时存在，内容已脱敏） */
  parentSnapshot?: {
    userId: string;
    userNickname?: string;
    comment: string;
    createdAt?: number;
  };
  /** 创建时间（毫秒时间戳） */
  createdAt: number;
  updatedAt?: number;
  /** 是否置顶 */
  pinned?: boolean;
  pinnedAt?: number;
}

响应（JSON）

返回标准分页结构。items 中同时包含顶级评论和回复；通过 parentId 区分——无 parentId 为顶级评论，有 parentId 为回复。

响应示例：

{
  "items": [
    {
      "id": "rev_001",
      "characterId": "abc123",
      "comment": "这个角色设定很有意思！",
      "userId": "user_001",
      "userNickname": "读者A",
      "createdAt": 1700000000000,
      "pinned": true,
      "pinnedAt": 1700100000000
    },
    {
      "id": "rev_002",
      "characterId": "abc123",
      "comment": "同感，剧情线也很棒",
      "userId": "user_002",
      "userNickname": "读者B",
      "parentId": "rev_001",
      "parentSnapshot": {
        "userId": "user_001",
        "userNickname": "读者A",
        "comment": "这个角色设定很有意思！"
      },
      "createdAt": 1700050000000
    }
  ],
  "nextCursor": "1700050000000"
}

示例

首次请求：

curl -X POST "https://xiangcao.ai/api/list-reviews" \
  -H "Content-Type: application/json" \
  -d '{
    "characterId": "abc123"
  }'

翻页：

curl -X POST "https://xiangcao.ai/api/list-reviews" \
  -H "Content-Type: application/json" \
  -d '{
    "characterId": "abc123",
    "cursor": "1700050000000"
  }'

错误处理

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