Public API

只读 REST API 挂载在 /api/v1/*。可在账号设置中创建 API Key；带 Key 调用享有更高限流并计入使用量。

端点

  • GET /api/v1/status
    需要 Bearer Key · 健康检查
  • GET /api/v1/posts
    可选 Bearer Key · 列表；query: cursor, limit, model, contentType, category, tag, q, sort
  • GET /api/v1/posts/:id
    可选 Bearer Key · 单条作品（id 或 slug）
  • GET /api/v1/taxonomy
    可选 Bearer Key · 模型 / 分类 / 标签
  • GET /api/v1/collections
    可选 Bearer Key · 公开收藏夹列表
  • GET /api/v1/collections/:id
    可选 Bearer Key · 公开收藏夹详情

Post 对象

GET /api/v1/posts 与 /api/v1/posts/:id 返回的 post 含 contentType（image | web | text | agent）、webUrl（网页作品时为 https URL，否则 null）、agentTask（Agent 任务结构化信息，否则 null）、embedBlocked、title、prompt、media、stats 等字段。视频作品仍是 contentType=image，并通过 media.videoUrl 暴露视频地址。

agentTask 包含 platform、platformLabel、intent、inputSummary、outputSummary、demoFiles、resultFiles；demoFiles/resultFiles 每项包含 name、url、key、bytes、contentType。

列表 query 支持 contentType=image|web|text|agent。若同时传 contentType 与 model，contentType 优先（例如 contentType=image 会忽略 model=web）。

认证

Authorization: Bearer pcafe_…

使用量

带有效 Key 的成功调用会写入 api_usage_daily（按 key / 日期 / endpoint 聚合）。

限流

匿名 120 次/分钟；带 Key 300 次/分钟。生产环境使用 Upstash Redis 滑动窗口；未配置时开发环境回退内存限流。