获取角色相册 · List Character Images

分页获取指定角色在对话中生成的剧情图片（角色相册）。常用于角色详情页、聊天内「相册」面板等场景。

接口地址

POST https://xiangcao.ai/api/list-character-images

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

鉴权

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

• 不带 Token 也能调用，但只能看到前 6 张预览图，且无法翻页。
• 携带 Token 时会按用户身份区分会员与非会员：

Authorization: Bearer <YOUR_API_KEY>

请求体（JSON）

平台策略：无论前端是否传入 createdAfter，服务端都会强制只返回最近 90 天内创建的图片。

类型定义（TypeScript）

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

interface ListCharacterImagesResponse {
  /** 本页图片列表 */
  items: ImageGenLog[];
  /** 下一页游标；为 null 表示已到末页（非会员始终为 null） */
  nextCursor: string | null;
  /** 非会员预览时附带，表示需要开通会员才能查看全部 */
  membershipRequired?: boolean;
}

interface ImageGenLog {
  id?: string;
  userId: string;
  archiveId: string;
  messageId: string;
  characterId: string;
  /** 图片 URL */
  url?: string;
  prompt?: string;
  /** 创建时间（毫秒时间戳） */
  createdAt: number;
  /** 审核状态：pending / approved / rejected / purged */
  reviewStatus?: ImageReviewStatus;
  // …其余生成参数字段见 ImageGenParams
}

响应（JSON）

返回标准分页结构。每条 items 记录对应一次对话生图日志，核心字段为 url（图片地址）和 messageId（关联的消息）。

非会员预览响应示例：

{
  "items": [ /* 最多 6 条 */ ],
  "nextCursor": null,
  "membershipRequired": true
}

会员分页响应示例：

{
  "items": [ /* 本页图片列表 */ ],
  "nextCursor": "eyJ2IjoxNzAwMDAwMDAwMDAwLCJwIjoxfQ"
}

示例

首次请求：

curl -X POST "https://xiangcao.ai/api/list-character-images" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "characterId": "abc123"
  }'

会员翻页：

curl -X POST "https://xiangcao.ai/api/list-character-images" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "characterId": "abc123",
    "cursor": "<上一页返回的 nextCursor>"
  }'

错误处理

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