Agent API · 面向机器的读取接口

让 Agent 生成之前，先查一条真的 prompt。

这套接口只做一件事：把人工核过出处的案例和完整 prompt 交给你的 Agent。免 key 就能开始用，量大了再申请 key 换更高配额。

向后兼容

已经在用的调用不受影响

这套接口一直是匿名开放的，现在依然是。不带认证头的请求照常返回同样的数据，只是加了一层按 IP 的频率软限；已经装了 goodcase Skill 的用户什么都不用改。认证头只有以 gc_ 开头时才会被当作 API key —— 请求里碰巧有别的 Authorization 头不会让你被拒。

§ 01 · 端点

两个端点，都是 GET

goodcase.ai 的 Agent API：免 key 即可调用，带 key 有更高日配额；每条案例附带可核验的溯源声明。

GET /api/public/cases · 案例列表

curl -s "https://goodcase.ai/api/public/cases?category=video&take=3&locale=zh-CN"

查询参数

category: image / video / web / copy / hardware，传别的值返回 400。
q: 关键词，匹配标题 / 摘要 / 创作者，大小写不敏感，中英文都行。
take: 返回条数 1-50，默认 20，越界自动钳制。
locale: 内容语言：zh-CN 或 en，默认 zh-CN。

GET /api/public/cases/{slug} · 单条全量

curl -s "https://goodcase.ai/api/public/cases/real-case-01-umesh-ai?locale=zh-CN"

在列表字段之外，额外返回 promptFull（完整 prompt）、editorNote（编辑点评）、labNote（实验笔记）、spreadScore（传播势能分）与 sourceHeatNote（热度计算说明）。

带 API key 调用

curl -s -D - \
  -H "Authorization: Bearer gc_xxxxxxxxxxxx" \
  "https://goodcase.ai/api/public/cases?take=3"

响应示例（截取）

{
  "count": 1,
  "locale": "zh-CN",
  "items": [
    {
      "slug": "tattoo-generator",
      "title": "Tattoo Generator",
      "category": "video",
      "source": "Comfy Workflows",
      "sourceUrl": "https://comfy.org/workflows/90d086fef9e3-90d086f…",
      "creator": "Rob",
      "summary": "这条工作流没有花哨的效果，胜在把纹身设计的沟通痛点解决得很实际…",
      "promptPreview": "Turn your tattoo design ideas into reality with …",
      "mediaType": "video",
      "mediaUrl": "https://…public.blob.vercel-storage.com/…",
      "posterUrl": "https://…public.blob.vercel-storage.com/…",
      "stabilityScore": 0,
      "recommendedModels": ["ComfyUI"],
      "costBand": "medium",
      "evidenceLevel": "L1",
      "tags": ["source-comfy", "workflow-method", "not-rerun"],
      "url": "https://goodcase.ai/cases/tattoo-generator",
      "contentLocale": "en",
      "availableLocales": ["zh-CN"],
      "isFallback": false,
      "provenance": {
        "sourceUrl": "https://comfy.org/workflows/90d086fef9e3-90d086fef9e3/",
        "verifiedAgainstSource": true,
        "method": "human-reviewed-source-match",
        "policyEffectiveAt": "2026-08-05",
        "note": "已发布案例的 prompt 均经人工核对与原帖一致…"
      },
      "likedCount": 0,
      "retestVoteCount": 0
    }
  ]
}

§ 02 · 溯源

每条案例都带一个可核验的出处声明

训练数据里最不缺的就是看起来很专业、其实从没人跑通过的 prompt。我们收录的每条案例都要求人工核对与原帖一致，平台拿产出图逆向重构出来的 prompt 一律不收。这条规则自 2026-08-05 起对全部发布内容生效，现在它以结构化字段出现在响应里，Agent 可以直接读，不用信我们嘴上说。

provenance

sourceUrl: 原帖地址。没有可公开原帖的案例这里是 null。
verifiedAgainstSource: prompt 是否经人工核对与原帖一致。没有原帖时为 false —— 无从对照就不做声明。
method: 核验方式标识。未来新增取值时，请按未知值降级处理。
policyEffectiveAt: 溯源准入规则的生效日期，不是逐条的核验时间戳。
note: 给人读的一句话说明，跟随 locale 参数。

§ 03 · 限额

两档配额，一套响应头

免 key 那档是软限：接口跑在 Serverless 上，每个实例各有一份内存计数窗口，所以实际放行量会高于标称值，实例回收时还会清零。它拦的是写错循环条件的脚本，不是精确配额。真正准确的配额挂在 key 上，计数落在数据库里，按 UTC 自然日重置。

档位	配额	怎么用
免 key	60 次 / 小时 / IP	什么都不用做，直接 curl。
带 key	默认 2,000 次 / 天，可按需调高	Authorization: Bearer gc_xxx，或 X-API-Key: gc_xxx。

限额响应头

X-RateLimit-Limit: 当前档位的上限。
X-RateLimit-Remaining: 本窗口 / 本日剩余次数。
X-RateLimit-Reset: 配额重置时刻，Unix 秒。
X-RateLimit-Scope: anonymous 或 key，用来确认你的 key 有没有生效。
Retry-After: 仅 429 时出现，建议等待秒数。

错误码

400: 参数非法，比如 category 传了未定义的值。
401: 认证头以 gc_ 开头但无效或已吊销。去掉它就退回免 key 档。
404: slug 不存在。
429: 触发频率软限或当日配额用尽，见 Retry-After。

§ 04 · 申请 key

v1 由人工签发

现在还没有自助注册。先手动发一批，把调用方是谁、怎么用、多少配额才合理弄清楚，再决定要不要做注册流 —— 过早自动化一个还没定型的流程，只会换来一堆僵尸 key。

01在反馈表里说明用途、预估日调用量和联系方式。
02我们签发后把明文 key 私下发给你，它只出现一次，我们这边只留哈希。
03把它放进 Authorization 头即可，不需要改任何其他调用代码。

API key去反馈表申请 →→

§ 05 · Skill

不想自己写请求？装 Skill

goodcase Skill 把上面这套接口包成自然语言查询，跨 Claude Code / Codex CLI / Cursor / Gemini CLI 通用，一行装完：

npx skills add LearnPrompt/goodcaseai --skill goodcase --global --copy --yes --full-depth

装好之后直接问你的 AI「最近有什么好案例」，它会自己来查，而不是凭训练数据编一个。

已经在用的调用不受影响

{ "count": 1, "locale": "zh-CN", "items": [ { "slug": "tattoo-generator", "title": "Tattoo Generator", "category": "video", "source": "Comfy Workflows", "sourceUrl": "https://comfy.org/workflows/90d086fef9e3-90d086f…", "creator": "Rob", "summary": "这条工作流没有花哨的效果，胜在把纹身设计的沟通痛点解决得很实际…", "promptPreview": "Turn your tattoo design ideas into reality with …", "mediaType": "video", "mediaUrl": "https://…public.blob.vercel-storage.com/…", "posterUrl": "https://…public.blob.vercel-storage.com/…", "stabilityScore": 0, "recommendedModels": ["ComfyUI"], "costBand": "medium", "evidenceLevel": "L1", "tags": ["source-comfy", "workflow-method", "not-rerun"], "url": "https://goodcase.ai/cases/tattoo-generator", "contentLocale": "en", "availableLocales": ["zh-CN"], "isFallback": false, "provenance": { "sourceUrl": "https://comfy.org/workflows/90d086fef9e3-90d086fef9e3/", "verifiedAgainstSource": true, "method": "human-reviewed-source-match", "policyEffectiveAt": "2026-08-05", "note": "已发布案例的 prompt 均经人工核对与原帖一致…" }, "likedCount": 0, "retestVoteCount": 0 } ] }

每条案例都带一个可核验的出处声明

两档配额，一套响应头

档位

配额

怎么用

免 key

60 次 / 小时 / IP

什么都不用做，直接 curl。

带 key

默认 2,000 次 / 天，可按需调高

Authorization: Bearer gc_xxx，或 X-API-Key: gc_xxx。