想给 public-apis 提交一条新 API 的开发者卡住的地方往往不是找不到服务而是不知道维护者到底按什么标准验收。与其自己逐行啃 CONTRIBUTING 和 README 规范不如把这件事交给已经配好模型的 Agent先到 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentpublic_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_sourcetaotoken_aicg_blog_endutm_contentpublic_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_KEYYOUR_API_KEY如果你同时用多个供应商用 CC Switch 这类切换工具会省事得多。它需要填的就是三件套配置项填写内容Base URLhttps://taotoken.net/apiAPI Key控制台创建的YOUR_API_KEYModel与所选供应商匹配的模型 ID三件套对齐之后切换供应商就是一次点击的事不用每次手改两个配置文件。Key 的创建入口在这里https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentpublic_apis_key 。如果你还没决定用哪条通道可以先在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentpublic_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_sourcetaotoken_aicg_blog_endutm_contentpublic_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这类宣传语AuthNo/apiKey/OAuth等枚举值写需要注册这种非枚举描述HTTPSYes/No服务端支持但文档没写凭感觉填 YesCORSYes/No/Unknown不确定时留空而不是填UnknownDescription 的写法值得单独说一句。既然是给选型的人看的就应该回答这个服务能拿到什么数据而不是这个服务有多好。比如提供全球主要城市的历史气温、降水与风力数据就比强大的天气数据解决方案有用得多也不会被当成软广。提交前把这一行放进目标分类里确认三件事排序位置正确、前后行的字段格式一致、管道符数量对得上。表格错位在渲染时会直接崩这类问题即使内容正确也会被打回。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?citybeijing | head -c 500返回结构对不上通常意味着文档滞后于接口。这种情况先别提交把文档更新到与接口一致再走提交流程——否则维护者验证时同样会发现不一致问题只是往后延了一轮。对于想批量核对多个候选服务的开发者可以让 Agent 按同一套模板逐条跑检查、汇总成表。用 TaoToken 的 Coding Plan 跑这类重复性核对任务比较合适成本和额度都更可控https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentpublic_apis_plan 。7. 把三份产物一起提上去回到最初的场景你想给 public-apis 提交一条新 API需要证明的不是这个服务很好用而是它满足收录标准且我用准确的字段把它描述清楚了。围绕这个目标整个流程可以收敛成三个动作第一先把模型通道配好。Claude Code 用ANTHROPIC_*写进settings.jsonCodex 用config.toml配model_providers多供应商切换就用 CC Switch 填三件套Base URL 统一为https://taotoken.net/api。第二让 Agent 读贡献说明和规范文档产出收录标准清单逐条对照你的服务打勾不满足的项要么补齐、要么先不提交。第三产出提交格式示例和文档缺口检查表把表格行按字母顺序放好把文档里缺的配额、商用条款、CORS 说明补上再用巡检脚本确认链接返回 200、最小请求返回结构一致。三份产物齐了PR 里的信息密度就上来了维护者能看到你已经逐条核对过标准也能顺着文档链接快速验证字段真假。这比只贴一行表格要省掉很多轮往返。需要完整配置说明的可以参考 Claude Code 接入文档里面有环境变量和参数细节https://taotoken.net/doc/ClaudeCodeAnthropic?utm_sourcetaotoken_aicg_blog_endutm_contentpublic_apis_doc 。还没有 Key 的话先去控制台创建一个再回到 Agent 里跑上面的提示词https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentpublic_apis_final 。如果你更习惯先在网页里把规范问清楚再动手模型对话页也可以直接用来做这一步https://taotoken.net/models/detail/chat?utm_sourcetaotoken_aicg_blog_endutm_contentpublic_apis_chat 。
