1. 从 Claude Code 的 404 和 CORS 报错说起先把 TaoToken Key 准备好我在 Claude Code 里输入过一句很典型的需求“帮我找一个免费天气 API能直接在前端fetch最好不用注册。”Agent 很快给了三个候选但真正跑起来时问题一个接一个第一个链接打开是 404第二个本地curl能通浏览器控制台却报跨域第三个标着AuthapiKey文档里还写着免费额度每月几百次。代码没写错错在选型入口太旧也错在没有先给 Agent 一个稳定的模型调用通道。如果你也是第一次接触 public-apis 这类公共 API 目录建议把顺序调过来先在 TaoToken 官网拿到模型调用的 Key再让 Agent 按“天气、地图、新闻”等关键词去 50 多个分类里定位最后由你在本地执行最小请求验证。模型调用的 Base URL 固定写成https://taotoken.net/apiKey 占位符统一用YOUR_API_KEY。拿 Key 的入口在这里https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentpublicapis_intro 。这样 agent 负责缩小范围你负责验证可用性不会把“目录里存在”误认为“生产可用”。public-apis 的价值不是提供统一 API而是把不同服务的文档入口按场景摆在一起。它更像一张索引天气、地图与地理编码、财经、新闻、交通、图片、文本分析、开放数据、测试数据、机器学习等分类都在里面。对初次接触目录的开发者来说难点不是找不到链接而是分类太多、字段太多、链接会过期。下面用一条可复现的路径把“目录定位”和“TaoToken 模型调用”接起来。2. public-apis 不是统一 API50 多个分类先映射再定位第一次打开 public-apis很容易把它当成一个 API 平台。实际上它只做了一件事把各家的文档入口、简短说明、鉴权方式、HTTPS、CORS 状态列出来。真正的请求仍然要发到对应服务配额、条款、数据授权也由对应服务决定。因此正确姿势是先定位分类再挑候选最后验证。50 多个分类不需要背。你只要把业务关键词映射到分类名再让 Agent 在本地目录里检索。比如“天气”大概率落在 Weather“地图”“经纬度”“路线规划”会分散在 Maps、Geocoding、Transportation“新闻”“资讯”“热点”通常看 News“汇率”“股票”“加密货币”要看 Currency Exchange、Finance、Cryptocurrency“做演示页缺假数据”直接翻 Test Data。下面这张表可以作为第一版分类定位表你的关键词对应分类典型条目关注点初次筛选建议天气、温度、预报Weather当前天气、逐小时预报、历史天气优先看 HTTPSYes前端使用还要看 CORS地图、路线、地理编码Maps、Geocoding、Transportation地图瓦片、地址转经纬度、路径规划注意商用限制和调用配额新闻、资讯、热点News头条、搜索、归档、地区新闻先确认语言覆盖和更新时间汇率、股票、财经Currency Exchange、Finance、Cryptocurrency实时汇率、历史 K 线、行情免费层通常有限流先跑最小请求测试数据、假数据Test Data用户、订单、图片占位、随机文本Demo 首选但仍要验证响应格式开放数据、政府数据Open Data、Government人口、经济、公共设施、交通注意授权条款和更新频率文本分析、NLPText Analysis情感分析、关键词、翻译看文本长度限制和调用次数图片、视频Images、Video占位图、图库、视频元数据版权和 CORS 要单独确认机器学习、数据集Machine Learning模型、数据集入口不一定提供 HTTP API健康、医疗Health疾病、药品、健身隐私和合规优先科学、数学Science Math天文、化学、数学计算文档完整度差异大有了这张表Agent 的工作就从“全网找 API”变成“在已知分类里筛选”。你可以把下面这段提示词交给 Claude Code、Codex 或其他 coding agent。注意Agent 只负责读目录、整理候选不要让它直接连生产库也不要把请求验证交给它自动执行。你是我的 API 选型助手。请基于我本地 public-apis 目录中的 README 和分类索引完成以下任务 1. 按关键词「天气、地图、新闻、汇率、测试数据」定位分类 2. 每个分类列出 3 个候选条目只记录服务名、分类、Auth、HTTPS、CORS、文档入口备注 3. 不要编造不存在的服务字段缺失就写 Unknown 4. 输出一份 Markdown 分类定位表以及一份 candidates.tsv 5. 不要直接给出生产接入建议所有请求验证命令由我在本地执行。这段提示词的关键是“本地目录”和“不要编造”。公共 API 目录经常变化Agent 如果凭记忆回答很容易给出已经下线的服务。让它基于本地文件做检索至少能保证候选来自当前目录而不是模型幻觉。3. 用关键词驱动 Agent天气、地图、新闻分别落到哪些分类把关键词交给 Agent 后不要只看它返回的服务名。你需要让它同时输出“为什么落在该分类”和“下一步验证什么”。例如“天气”不只是 Weather某些历史气候数据可能落在 Science Math 或 Open Data“地图”不只是 Maps地址解析可能在 Geocoding路线规划可能在 Transportation“新闻”也不只是 News部分聚合接口会放在 Data 或 Open Data 里。可以让 Agent 按下面的结构输出方便你直接贴进项目文档| 关键词 | 主分类 | 备选分类 | 候选数量 | 主要风险 | 下一步 | | --- | --- | --- | --- | --- | --- | | 天气 | Weather | Open Data、Science Math | 5 | 免费额度、CORS | 选 2 个跑最小请求 | | 地图 | Maps、Geocoding | Transportation | 6 | 商用限制、配额 | 核对条款和 HTTPS | | 新闻 | News | Data | 4 | 语言覆盖、归档深度 | 检查更新时间 | | 汇率 | Currency Exchange | Finance | 5 | 限流、实时性 | 检查响应延迟 | | 测试数据 | Test Data | - | 4 | 数据格式、随机性 | 本地生成小样本 |同时让 Agent 输出candidates.tsv字段不要太多够用即可name category auth https cors doc_hint verify_status 示例天气服务 Weather apiKey Yes Yes 文档入口备注 未验证 示例地图服务 Maps No Yes Unknown 文档入口备注 未验证这里的doc_hint只记录文档入口备注不要把完整 URL 直接写进代码或配置。真正请求时用环境变量承载地址避免把候选地址硬编码进仓库。verify_status初始为“未验证”后面由你的本地脚本更新。Agent 生成表格后你还要做一次人工复核分类是否合理字段是否从目录中真实读取Unknown是否被误写成Yes。这一步不需要模型打开目录对照即可。第一次接触目录的开发者最容易跳过复核结果把 CORS 为 No 的接口接进前端上线后才在浏览器里报错。4. Auth、HTTPS、CORS 三列过滤比“免费”更先看目录里每个条目通常会有 Auth、HTTPS、CORS 三列。很多人只看“免费”两个字但这三列更能决定接口能不能用。Auth 表示鉴权方式。No说明请求本身不要求认证信息但不代表没有额度、频率限制或使用条款apiKey通常意味着要先获得密钥OAuth则需要处理授权流程和令牌刷新。对初次选型来说如果只是做本地 Demo可以优先看No或apiKey如果要上线必须回到对应文档核对配额、价格和隐私政策。HTTPS 表示是否提供加密访问。生产项目里尽量避免使用明文 HTTP。CORS 更直接影响 Web 前端标为Yes的服务浏览器跨域调用通常更省事标为No时浏览器直接fetch很可能被拦截需要放到服务端代理标为Unknown时自己要带Origin头测一次。下面是一个简化判断矩阵AuthHTTPSCORS适合场景风险提示NoYesYes本地 Demo、前端快速验证仍可能有限流和条款限制apiKeyYesYes小规模前端或服务端调用Key 不能暴露在前端apiKeyYesNo服务端代理、定时任务前端直接调用会跨域失败OAuthYesUnknown需要用户授权的场景授权流程复杂先做 PoCNoNoNo仅内网或临时测试不建议进生产验证 CORS 可以用一条本地命令地址来自你的环境变量不在文章里暴露具体站外地址export API_URL把候选接口地址填在这里 curl -sS -I -H Origin: http://localhost:3000 $API_URL \ | grep -i access-control-allow-origin如果没有返回access-control-allow-origin就不要假设浏览器能直接调用。验证状态码和响应时间curl -sS -o /tmp/api_body.json \ -D /tmp/api_headers.txt \ -w http_code%{http_code}\ntime_total%{time_total}\n \ $API_URL这些命令都在你的本地机器执行。不要让 Agent 直接连生产数据库也不要把数据库连接串交给模型。API 选型阶段只处理公开文档入口和最小 HTTP 请求不涉及生产数据。5. 让 Agent 产出分类定位表、候选链接与验证脚本可复现的产出不是一段聊天记录而是三个文件category-map.md、candidates.tsv、verify-report.tsv。第一个文件记录关键词到分类的映射第二个文件记录候选条目第三个文件记录本地验证结果。这样即使换了一个 Agent 或换了一个模型工作流仍然能继续。先让 Agent 生成category-map.md内容包含分类名、关键词、候选数量、主要风险。再让它把候选写入candidates.tsv。最后你用本地脚本逐个验证。链接检查可以这样写#!/usr/bin/env bash set -euo pipefail INPUTcandidates.tsv OUTverify-report.tsv printf name\tcategory\thttp_code\tcontent_type\tlatency_s\n $OUT while IFS$\t read -r name category auth https cors doc_hint url; do [ $name name ] continue if [ -z ${url:-} ]; then printf %s\t%s\tSKIP\t-\t-\n $name $category $OUT continue fi code$(curl -L -s -o /dev/null -w %{http_code} --max-time 8 $url || true) ctype$(curl -L -s -o /dev/null -w %{content_type} --max-time 8 $url || true) latency$(curl -L -s -o /dev/null -w %{time_total} --max-time 8 $url || true) printf %s\t%s\t%s\t%s\t%s\n \ $name $category $code $ctype $latency $OUT done $INPUT echo 验证完成结果写入 $OUT注意url列由你本地填写不要把真实地址提交到公开仓库。脚本只做状态码、内容类型和延迟检查。对返回 404 或 410 的条目先标记为“链接失效”对 403、429、超时不要立刻判定服务不可用可能是缺少 Key、触发限流或扫描环境导致。社区里曾有人扫描目录并报告大量链接异常但这类结果通常只适合当线索最终仍要以你当前网络和官方文档为准。验证完成后verify-report.tsv会告诉你哪些候选值得继续看文档。此时再回到分类表按业务场景选三到五个候选分别跑一个最小请求。不要一次性接入十个服务也不要只看服务名做决定。6. TaoToken 接入配置Claude Code、Codex、CC Switch 分开填在让 Agent 读目录之前先保证模型调用通道稳定。TaoToken 的 Base URL 是https://taotoken.net/apiKey 占位符用YOUR_API_KEY。如果你还没有 Key可以从官网入口开始https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentpublicapis_getkey 。创建 Key 的控制台入口在文末统一给出。Claude Code 可以使用settings.json或环境变量。下面是一个最小settings.json示例{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: YOUR_API_KEY } }如果使用 shell 环境变量可以这样写export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYYOUR_API_KEY claudeCodex 不要套用ANTHROPIC_*它使用自己的config.toml。可以按下面结构配置模型名按你控制台实际可用的模型填写model 按控制台可用模型填写 model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY然后在 shell 中提供 Keyexport TAOTOKEN_API_KEYYOUR_API_KEYCC Switch 可以按“三件套”理解Provider 名称、Base URL、API Key。填写时不要混用供应商字段Provider: TaoToken Base URL: https://taotoken.net/api API Key: YOUR_API_KEY Model: 按控制台可用模型填写配置完成后先跑一条最小对话请求确认模型能正常返回。注意 Base URL 不加 UTM 参数UTM 只用于官网入口统计。验证命令如下export TAOTOKEN_API_KEYYOUR_API_KEY export TAOTOKEN_BASE_URLhttps://taotoken.net/api curl -sS $TAOTOKEN_BASE_URL/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: 按控制台可用模型填写, messages: [ {role: user, content: 只返回 ok} ] }如果返回鉴权失败先检查 Key 是否复制完整、Base URL 是否是https://taotoken.net/api如果返回模型不存在检查模型名如果超时检查本地网络和终端代理设置。不要在 Codex 配置里填ANTHROPIC_*也不要在 Claude Code 配置里填 Codex 的model_provider。7. 从候选链接到最小请求本地验证命令与排障清单模型通道通了之后再回到 public-apis 的候选条目。此时你手里应该有分类定位表、候选列表和验证脚本。建议按以下顺序执行从category-map.md里选一个业务关键词比如“天气”。从candidates.tsv里挑 3 个候选记录 Auth、HTTPS、CORS。用本地脚本检查文档入口状态码过滤掉 404、410。对存活候选跑最小请求保存响应头和响应体。根据响应质量、限流提示、文档完整度保留 1 到 2 个。把最终结论写回category-map.md标注“已验证”或“放弃”。最小请求不要直接请求业务数据可以先请求一个健康检查或根路径export API_URL候选接口地址 export API_KEY如果该接口需要 Key从对应文档获取 curl -sS -i $API_URL \ -H Accept: application/json \ -H Authorization: Bearer $API_KEY \ --max-time 10如果接口不需要 Key去掉Authorization头。如果接口使用 query 参数传 Key按文档调整不要照搬。验证时重点看五件事HTTP 状态码是否为 2xx响应头是否包含 CORS 允许字段返回内容是否为预期 JSON 或文本是否出现rate limit、quota exceeded等提示文档里的免费层是否仍然有效。常见排障对照如下现象可能原因处理方式404 / 410链接迁移或服务下线标记失效回目录找替代403缺少 Key、地区限制、反爬看文档不要直接判定不可用429触发限流降低频率核对配额CORS 报错目录标 CORSNo 或 Unknown改用服务端代理AuthNo 但返回 401目录字段过时以官方文档为准HTTPSNo明文传输生产环境避免使用响应很慢网络或服务端限流增加超时换候选Agent 给出不存在服务模型幻觉要求基于本地目录并复核链接过期是公共 API 目录的常态。服务会改版、迁移、合并或停止维护。目录适合当选型起点不适合当成永久清单。把验证脚本留在仓库里每次接入前跑一遍比记一堆链接更可靠。8. 把模型调用接回工作流TaoToken 的 CTA 路径当分类定位表、候选列表和验证报告都跑通后Agent 就不再是“随口推荐 API”的聊天机器人而是一个能读目录、能整理候选、能按关键词定位分类的选型助手。你只需要把模型调用通道固定下来Base URL 用https://taotoken.net/apiKey 用YOUR_API_KEY官网入口在这里https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentpublicapis_workflow 。如果你还没有开始配置可以按“模型对话 → Coding Plan → 创建 Key → Claude Code 文档”的顺序走模型对话先试一条最小请求确认模型能返回。https://taotoken.net/models/detail/chat?utm_sourcetaotoken_aicg_blog_endutm_contentpublicapis_chatCoding Plan需要长期让 Agent 读目录、生成定位表时查看适合的编码方案。https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentpublicapis_coding创建 Key在控制台生成或管理 API Key填入YOUR_API_KEY的位置。https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentpublicapis_keysClaude Code 文档需要把 Claude Code 接到 TaoToken 时按文档填写ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY。https://taotoken.net/doc/ClaudeCodeAnthropic?utm_sourcetaotoken_aicg_blog_endutm_contentpublicapis_claudecode最后再强调一次边界public-apis 里的接口由各自服务提供免费额度、CORS、Auth 和链接状态都可能变化TaoToken 负责的是模型调用通道。让 Agent 帮你定位分类、生成候选、整理表格但所有第三方请求验证都在本地执行不要把生产数据库、真实用户数据或长期密钥交给 Agent。这样你既能用好 50 多个分类的目录又不会把“目录里能找到”误当成“线上一定能用”。