请求头

• 认证：X-API-Key: h3k_... 或 Authorization: Bearer <access_token>
• 内容类型：Content-Type: application/json
• 浏览器会话由 httpOnly Cookie 自动携带

分页

列表接口统一使用：

• page：页码，从 1 开始
• page_size：每页数量，默认 20，上限一般是 50 或 100

响应结构：

{
  "items": [],
  "total": 100,
  "page": 1,
  "page_size": 20
}

时间格式

时间字段统一是 ISO 8601 UTC 字符串，例如：

2026-08-20T12:00:00.000000+00:00

前端展示时再转本地时区，接口不做本地化。

幂等

• 点赞/收藏重复调用不会重复计数。
• 一个任务只能发布一次作品，重复发布会返回 409。
• 任务完成接口由 Worker 调用，重复完成不会重复扣费/退款。

错误结构

所有错误统一：

{ "detail": "错误信息" }

部分接口会带 Retry-After 头，例如限流。

限流

• 默认每分钟 20 次，按 API Key 哈希和 IP 分别计数。
• 命中返回 429，看 Retry-After 再重试。