API Key 怎么创建获取?国内开发者完整步骤 + 报错对照表(2026)
想调 Claude / GPT 的 API,第一步是拿到 Key。讲清官方渠道卡在哪、中转怎么几分钟拿到 Key、base_url 为什么必须带 /v1,以及 401/404/余额报错逐条对照怎么修。
1. API Key 是什么,为什么必须有
API Key 是一串密钥,你的程序每次向模型服务发请求都要带上它,作用是回答两个问题:你是谁,以及这次调用按谁的余额计费。所以它本质上等同于一把「支付凭证 + 身份证」,谁拿到它谁就能用你的余额调用。这也解释了为什么后面关于 Key 安全的那几条不是小题大做——Key 泄露的直接后果是别人拿你的钱调模型,而且往往是在你毫无察觉的情况下持续发生。理解这一点,你就知道为什么正规做法一定是「Key 存在服务端、用环境变量读取」,而不是图方便写进前端代码或者提交到代码仓库里。
2. 官方渠道卡在哪一步
先说清楚事实:官方渠道本身没有问题,也是最直接的方式——如果你有条件走通,直接用官方是很好的选择。国内开发者遇到的障碍通常不在注册环节,而在绑卡:官方要求先绑定一张能通过风控的海外信用卡并成功充值,之后才能在控制台创建 Key。卡点就在这里——账号注册好了,卡付不进去;或者刚充值成功就被风控拦下。这是发卡地风控导致的结构性问题,不是你哪一步操作错了。所以国内开发者的选择通常是两条:要么想办法解决海外卡这一环,要么走一个支持人民币充值的兼容中转,把绑卡这一步整个绕过去。
3. 用兼容中转建 Key:四步
以 cocodot 为例,整个过程几分钟、不需要海外卡:① 注册账号并验证邮箱;② 用支付宝小额充值——注意没有免费额度,余额必须大于 0 才能调用,建议第一次只充一点点,先把链路跑通;③ 进 AI API 控制台,勾选同意 API 条款,创建 API Key;④ 立刻把 Key 复制保存好——它通常只在创建时完整显示一次,页面关掉就看不到了,丢了只能吊销重建。建议直接存进密码管理器,而不是先粘到聊天窗口或者随手记在某个文件里。拿到 Key 之后,你就有了一个能走标准接口调用的凭证,下一节讲怎么接。
4. 怎么把 Key 用起来(以及那个必须带的 /v1)
这类中转是 OpenAI 兼容的,意思是你可以继续用 OpenAI 官方 SDK,只改两个参数:把 `base_url` 指到中转地址、`api_key` 填你新建的 Key,其余调用 `chat.completions` 的代码一行都不用动。最高频的配置错误是 base_url 末尾漏了 `/v1`——写成 `https://cocodot.co/api/ai` 会让所有请求 404,正确的是 `https://cocodot.co/api/ai/v1`。SDK 会自己在这个地址后面拼 `/chat/completions`,所以你只需要给到 `/v1` 这一层。同样的一组参数也适用于那些支持「自定义 OpenAI 接口」的桌面客户端和编辑器插件:填的就是这同一个 base_url 和同一个 Key。
5. 模型代号:别背,直接查
很多教程会写死「某某代号 = 某某模型」,但模型是会更新换代的,写死的对照表过一阵子就不准了。更可靠的做法是直接查当前可用列表——这类平台一般提供 OpenAI 标准的模型列表接口,cocodot 的这个接口是公开的、不需要 Key 就能看: ```bash curl https://cocodot.co/api/ai/v1/models ``` 返回的是标准格式的型号清单,把你要用的那个 `id` 复制到代码的 `model` 字段即可。养成「用之前先拉一次列表」的习惯,比背代号可靠得多,也能第一时间发现某个型号是不是已经下架。控制台的模型页同样能看到当前在售型号,两个地方对得上就没问题。
6. Key 安全:三条必须做的
① 绝不把 Key 写进前端代码或提交到代码仓库。前端代码是公开的,任何人打开浏览器都能看到;提交到公开仓库的密钥会被自动化程序在很短时间内扫走。正确做法是 Key 只存在服务端,通过环境变量读取,并把配置文件加进 `.gitignore`。② 一个项目一个 Key。这不是洁癖:出问题时你能只吊销那一个 Key,而不必把所有项目一起停掉,同时也方便按项目看用量、定位是谁在烧钱。③ 怀疑泄露立刻吊销重建,不要犹豫也不要「先观察一下」——吊销重建的成本是几分钟,继续用下去的成本是余额。
7. 上线前跑一遍的自检清单
把 Key 接进项目之后,上线前建议逐条过一遍:① 小额跑通一次真实调用,确认返回正常、计费正常,再往上加量;② 确认 Key 不在代码仓库里——用 `git log -p` 搜一遍历史,注意即使后来删掉了,历史提交里仍然留着;③ 给调用加超时和重试,模型请求比普通接口慢得多,默认超时经常不够,长回答建议用流式输出;④ 把模型代号做成配置而不是写死在代码里,换模型时不用改代码重新发版;⑤ 加一层用量监控,至少能看出「今天调了多少、花了多少」,余额被异常消耗时你能第一时间发现,而不是等余额见底才知道。
报错 → 根因 → 怎么修(照着排,别乱试)
| 你看到的报错 | 最可能的根因 | 怎么修 |
|---|---|---|
| 401 / Unauthorized | Key 填错、或没按 Bearer 方式带上 | 重新复制 Key;确认用的是 api_key 参数而不是塞进别处 |
| 404 / Not Found | base_url 末尾少了 /v1 | 补成 .../api/ai/v1,这是最常见的一个 |
| model not found | 模型代号写错或该型号已下架 | 拉一次模型列表,复制当前可用代号 |
| 余额不足类提示 | 账户余额为 0(无免费额度) | 先充值,余额大于 0 才能调用 |
| 一直超时 / 连不上 | 网络出口或客户端超时设太短 | 延长超时;流式输出更适合长回答 |