想给 public-apis 提交一条新 API 的开发者，卡住的地方往往不是找不到服务，而是不知道维护者到底按什么标准验收。与其自己逐行啃 CONTRIBUTING 和 README 规范，不如把这件事交给已经配好模型的 Agent：先到 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_content=public_apis_intro 拿一个 Key，把工具的 Base URL 指向https://taotoken.net/api，再让 Agent 去读仓库的贡献说明与文档要求，最后产出三份能直接落到 PR 里的东西——收录标准清单、提交格式示例、文档缺口检查表。这样你提交的不是一条"看起来还行"的链接，而是一条经得起维护者逐列核对的条目。
public-apis 这个仓库本身是一个社区维护的公共 API 目录，收录的是可免费使用或至少提供免费层的服务入口，链接直接指向各家的文档或官网，方便先缩小选型范围。它的价值在于分类导航和字段规范，而不是统一网关——所以对提交者来说，真正需要研究的不是"有哪些 API"，而是"我的 API 要满足哪些条件、写成什么格式，才会被合进去"。
1. 使用者视角和提交者视角，看的是同一张表的两面
如果你只是来找数据，public-apis 的操作路径很短：进入某个分类，看服务名称、简短说明、文档链接，再到表格里的 Auth、HTTPS、CORS 三列判断能不能用在当前场景里。天气、地图与地理编码、财经、新闻、交通、图片、文本分析、开放数据、测试数据、机器学习等 50 多个分类基本覆盖了常见的数据需求。
但一旦你换成提交者视角，这三列就从"判断能不能用"变成了"必须如实填写"的字段：
Auth写的是鉴权方式，No表示请求不要求认证，apiKey表示要申请密钥，OAuth表示要走授权流程。填错的后果是维护者或其他开发者按你写的字段去调，直接拿不到数据。HTTPS写的是服务是否提供加密访问。这一列填Yes但实际只有 HTTP 端点，是最容易被退回的类型。CORS写的是浏览器跨域可用性。标Yes的服务，前端页面能直接调；标No的按仓库贡献说明只能在服务端使用；Unknown则需要自己确认后再填，不要凭感觉写。
也就是说，使用者看到的是"这个服务适不适合我"，提交者要回答的是"我能不能用准确的字段把这件事描述清楚"。后者要求的证据更硬——必须有文档页面支撑，而不是口头承诺。
想先把这套字段含义对着模型问清楚，可以打开模型对话页直接提问，让它逐列解释并结合你的服务给出填写建议：https://taotoken.net/models/detail/chat?utm_source=taotoken_aicg_blog_end&utm_content=public_apis_field 。不过这属于前置准备，真正的重头戏是让 Agent 去读仓库规范。
2. 先配 TaoToken：让 Claude Code 和 Codex 读得动仓库规范
提交前的核对工作，本质上是"读一堆 Markdown 规范 + 比对自家 API 文档 + 输出结构化清单"。这个流程非常适合交给编程 Agent 做，前提是它的模型通道要稳。把供应商切到 TaoToken 之后，Claude Code 和 Codex 都能用同一个 Key 和同一个 Base URL。
Claude Code 走的是settings.json里的ANTHROPIC_*环境变量：
{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY", "ANTHROPIC_MODEL": "claude-sonnet-4-5" } }把上面这段写进~/.claude/settings.json（或项目级的.claude/settings.json），重启 Claude Code 即可生效。注意ANTHROPIC_BASE_URL不要带路径后缀之外的斜杠，ANTHROPIC_AUTH_TOKEN填的就是你在控制台创建的 Key，模型 ID 以模型对话页实际显示为准。
Codex 走的是~/.codex/config.toml，字段体系完全不同，千万别把ANTHROPIC_*那一套搬过来：
model = "gpt-5-codex" model_provider = "taotoken" [model_providers.taotoken] name = "TaoToken" base_url = "https://taotoken.net/api" env_key = "TAOTOKEN_API_KEY" wire_api = "chat"对应的环境变量在 shell 里先导出：
export TAOTOKEN_API_KEY="YOUR_API_KEY"如果你同时用多个供应商，用 CC Switch 这类切换工具会省事得多。它需要填的就是三件套：
| 配置项 | 填写内容 |
|---|---|
| Base URL | https://taotoken.net/api |
| API Key | 控制台创建的YOUR_API_KEY |
| Model | 与所选供应商匹配的模型 ID |
三件套对齐之后，切换供应商就是一次点击的事，不用每次手改两个配置文件。
Key 的创建入口在这里：https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=public_apis_key 。如果你还没决定用哪条通道，可以先在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_content=public_apis_setup 看看当前的模型与套餐说明，再决定是走按量还是 Coding Plan。
配置好了之后，把下面这段提示词交给 Agent，让它先读规范、再产出草稿：
你是 public-apis 仓库的贡献审核助手。请按顺序完成： 1. 读取仓库根目录的 CONTRIBUTING.md 与 README.md 中与收录相关的章节， 提取「收录标准」与「提交格式」两部分的原文要求。 2. 阅读我要提交的服务文档（见下方粘贴内容），逐条比对收录标准， 输出一份带勾选项的收录标准清单，标出满足项与不满足项。 3. 按仓库现有表格格式，生成一行提交条目草案， 包括 API 名称、Description、Auth、HTTPS、CORS 五个字段。 4. 输出一份「文档缺口检查表」，列出我的文档里缺失、 但维护者可能追问的信息。 约束： - 不要臆造字段值，缺少依据的地方标注「待确认」并说明需要查哪个页面。 - 不要输出任何我未提供的 URL。 - 所有结论必须能对应到规范原文或我的文档内容。 我的服务文档： <paste here>这个提示词的关键约束是"缺少依据标注待确认"。很多提交被退回，不是因为服务不行，而是因为作者在 Auth 或 CORS 栏凭印象填了值，维护者一验证对不上。
3. 收录标准清单：把贡献说明拆成可勾选项
仓库的收录标准核心就几条，但每一条在执行时都有细节。下面这份清单可以直接拿去和你的服务逐项对照：
## public-apis 收录标准自检清单 ### 一、可用性门槛 - [ ] 服务可以完全免费使用，或者至少提供一个明确的免费层 - [ ] 不要求开发者先购买硬件、设备或其他付费服务才能访问 - [ ] 免费层不是「限时试用」且已过期的活动页面 ### 二、文档要求 - [ ] 提供规范、可公开访问的文档页面（不是官网首页、不是产品介绍页） - [ ] 文档中包含至少一个可参考的请求示例 - [ ] 文档说明了鉴权方式，且与条目里填写的 Auth 字段一致 - [ ] 文档说明了是否支持 HTTPS，且与条目里填写的 HTTPS 字段一致 - [ ] 文档说明了跨域策略，或明确给出了 CORS 响应头示例 ### 三、条目规范 - [ ] API 名称使用服务正式名称，不做营销化改写 - [ ] Description 为一句话说明，描述数据内容而非宣传语 - [ ] 条目插入到对应分类下，并保持该分类内按字母顺序排列 - [ ] 链接指向文档或官网，不使用短链、跳转页、affiliate 链接 - [ ] 不使用已存在的重复条目 ### 四、提交前验证 - [ ] 文档链接在无痕窗口可正常打开，返回 200 - [ ] 按文档跑通一个最小请求，确认返回结构与文档描述一致 - [ ] Auth 字段为 apiKey 时，确认免费层确实能拿到可用的 Key这份清单里最容易被忽略的是第三条里的"按字母顺序"。提交前先看一下目标分类的现有条目排到哪儿了，插错位置在 review 里是很常见的退回理由，改起来不难但会浪费一轮往返。
另外，"免费层"这个词在不同服务那里含义差别很大。有的免费层是每月固定额度，有的是限速但不限量，有的是只开放部分端点。你在 Description 里可以不展开，但自己心里要清楚，因为维护者或者后续使用者很可能会追问。
如果你想让 Agent 帮你把这份清单和你的实际服务逐条打勾，可以先把规范原文和你的文档一起喂给它。规范原文可以通过 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_content=public_apis_rule 这条入口拿到 Key 后直接用模型对话拉取总结，省去手工复制粘贴。
4. 提交格式示例：一行表格怎么写才不会被退回
public-apis 的条目是 Markdown 表格行，格式本身很简单，但每个字段都有明确的写法约定。一个典型的条目长这样：
| API | Description | Auth | HTTPS | CORS | | :--- | :--- | :--- | :--- | :--- | | [Example Weather](https://example.com/docs) | 全球城市实时天气与 7 天预报 | `apiKey` | Yes | Yes |拆开看每一列的写法：
| 列名 | 写法 | 常见错误 |
|---|---|---|
| API | [服务名](文档链接)，用服务正式名称 | 只写名字不带链接，或链接指向首页 |
| Description | 一句话，说明提供什么数据 | 写成"最好用的天气 API"这类宣传语 |
| Auth | No/apiKey/OAuth等枚举值 | 写"需要注册"这种非枚举描述 |
| HTTPS | Yes/No | 服务端支持但文档没写，凭感觉填 Yes |
| CORS | Yes/No/Unknown | 不确定时留空，而不是填Unknown |
Description 的写法值得单独说一句。既然是给选型的人看的，就应该回答"这个服务能拿到什么数据"，而不是"这个服务有多好"。比如"提供全球主要城市的历史气温、降水与风力数据"就比"强大的天气数据解决方案"有用得多，也不会被当成软广。
提交前把这一行放进目标分类里，确认三件事：排序位置正确、前后行的字段格式一致、管道符数量对得上。表格错位在渲染时会直接崩，这类问题即使内容正确也会被打回。
5. 文档缺口检查表：维护者会追问什么
收录标准只说了"要有规范文档"，但什么叫规范，得靠这份检查表补齐。下面这些条目，维护者和后续使用者都可能追问，文档里缺哪一项，就先补哪一项：
## API 文档缺口检查表 ### 入门信息 - [ ] 服务的一句话定位与覆盖范围（哪些数据、哪些地区） - [ ] 明确的文档入口 URL，且该页面无需登录即可访问 ### 鉴权 - [ ] 鉴权方式说明（无鉴权 / API Key / OAuth） - [ ] Key 的申请路径与是否需要审核 - [ ] Key 的传递方式（Header 名、Query 参数名） ### 配额与限制 - [ ] 免费层的额度（每日/每月请求数） - [ ] 速率限制（每秒/每分钟请求数） - [ ] 超限后的响应行为（429 还是直接拒绝） ### 请求与响应 - [ ] 至少一个完整的 curl 或 HTTP 请求示例 - [ ] 响应字段说明与示例 JSON - [ ] 错误码列表与含义 ### 合规与稳定性 - [ ] 数据来源与授权说明 - [ ] 商用条款（免费层能否用于商业项目） - [ ] 服务条款与隐私政策页面 - [ ] 版本变更或弃用策略 ### 跨域 - [ ] CORS 支持情况说明 - [ ] 若支持，给出允许的来源与响应头示例其中"免费层能否商用"这一条，很多个人开发者的文档里是缺失的。这不会直接导致条目被拒，但如果你在 Description 或文档里暗示可以商用而实际条款不允许，后续会被修掉。写清楚反而省事。
CORS 那一项也值得认真对待。仓库把No明确解释为"只能在服务端使用"，所以如果你的 API 实际支持浏览器直连，一定要在文档里给出响应头示例，否则填Unknown会让前端开发者绕道走。
6. 链接巡检：把 404 和 410 挡在提交之前
这个目录里最现实的问题是链接会过期。服务改版、迁移、下线，都会让原本正常的文档链接失效。仓库当前的 issue 里就有社区用户做过两轮 README 扫描，报告发现了 89 个返回 404 或 410 的链接，同时排除了 403、429、超时这类可能由扫描环境造成的状态码。这个数字来自单个社区反馈，不是维护者的最终清理结论，但它说明了一件事：链接可用性必须自己验证。
你提交前至少要在无痕窗口里把文档链接打开一遍。如果条目数量多，或者你想顺便帮仓库做一次巡检，可以用下面这个脚本：
#!/usr/bin/env bash # 从待检查的链接列表里逐条请求，按状态码分类输出 # links.txt 每行一个 URL，由你本地整理后生成 while read -r url; do [ -z "$url" ] && continue code=$(curl -o /dev/null -s -L --max-time 15 -w '%{http_code}' "$url") case "$code" in 200) echo "OK $code $url" ;; 404|410) echo "失效 $code $url" ;; 403|429) echo "待确认 $code $url" ;; 000) echo "超时 $code $url" ;; *) echo "异常 $code $url" ;; esac done < links.txt脚本在你本地跑，links.txt也由你自己生成，不要把它指向任何生产环境或内部系统。分档的意义在于：404和410基本可以判定为失效，需要替换；403和429很可能是限流或反爬导致的，换个网络环境或降低频率再试一次，别急着下结论；000是连接层面失败，同样需要复核。
除了链接本身，还要跑一次最小请求。选一个文档里给出的示例端点，带上YOUR_API_KEY发一次请求，确认返回结构和文档描述一致：
curl -s -H "Authorization: Bearer YOUR_API_KEY" \ "https://example.com/v1/weather?city=beijing" | head -c 500返回结构对不上，通常意味着文档滞后于接口。这种情况先别提交，把文档更新到与接口一致，再走提交流程——否则维护者验证时同样会发现不一致，问题只是往后延了一轮。
对于想批量核对多个候选服务的开发者，可以让 Agent 按同一套模板逐条跑检查、汇总成表。用 TaoToken 的 Coding Plan 跑这类重复性核对任务比较合适，成本和额度都更可控：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=public_apis_plan 。
7. 把三份产物一起提上去
回到最初的场景：你想给 public-apis 提交一条新 API，需要证明的不是"这个服务很好用"，而是"它满足收录标准，且我用准确的字段把它描述清楚了"。围绕这个目标，整个流程可以收敛成三个动作：
第一，先把模型通道配好。Claude Code 用ANTHROPIC_*写进settings.json，Codex 用config.toml配model_providers，多供应商切换就用 CC Switch 填三件套，Base URL 统一为https://taotoken.net/api。
第二，让 Agent 读贡献说明和规范文档，产出收录标准清单，逐条对照你的服务打勾，不满足的项要么补齐、要么先不提交。
第三，产出提交格式示例和文档缺口检查表，把表格行按字母顺序放好，把文档里缺的配额、商用条款、CORS 说明补上，再用巡检脚本确认链接返回 200、最小请求返回结构一致。
三份产物齐了，PR 里的信息密度就上来了：维护者能看到你已经逐条核对过标准，也能顺着文档链接快速验证字段真假。这比只贴一行表格要省掉很多轮往返。
需要完整配置说明的，可以参考 Claude Code 接入文档，里面有环境变量和参数细节：https://taotoken.net/doc/ClaudeCodeAnthropic?utm_source=taotoken_aicg_blog_end&utm_content=public_apis_doc 。还没有 Key 的话，先去控制台创建一个，再回到 Agent 里跑上面的提示词：https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=public_apis_final 。如果你更习惯先在网页里把规范问清楚再动手，模型对话页也可以直接用来做这一步：https://taotoken.net/models/detail/chat?utm_source=taotoken_aicg_blog_end&utm_content=public_apis_chat 。
