API、API Key 和 Token 到底是什么？一次讲清

“把 Token 填进去”是一句很危险的教程

新手照着教程接 API 时，经常会看到一句话：“把 Token 填到这里。”问题是，这个 Token 可能指 API Key，也可能是 OAuth Access Token，还可能只是模型用量里的文本计量单位。

三者完全不是一回事。

API 是程序之间约定好的入口。API Key 是服务识别调用者的一种秘密凭证。Token 在模型语境里可以表示文本计量，在鉴权语境里又可能代表一个带权限和有效期的凭证。

所以看到“填 Token”时不要马上复制。先确认变量名、创建它的官方页面、接收它的程序，以及这串值一旦泄露能做什么。把这四件事问清，很多接入错误会在请求发出前消失。

一次 API 请求到底发生了什么

网页聊天是给人操作的界面，API 是给程序使用的接口。一个最小请求通常包含五部分：

1. 地址：请求发往哪个 endpoint。
2. 方法：例如 GET 或 POST。
3. 请求头：内容类型、鉴权方式等。
4. 请求体：模型、输入和参数。
5. 响应：状态码、结构化数据或错误。

以 OpenAI 当前官方快速开始的 Responses API 为例，curl 请求结构可以写成：

curl https://api.openai.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "YOUR_CURRENT_MODEL_ID",
    "input": "只回复：连接成功"
  }'

YOUR_CURRENT_MODEL_ID 是占位符，应从操作当天的官方文档选择当前可用模型。不要从旧文章复制一个可能已停用的模型名。

这段命令也不应把真实密钥直接写进去。Authorization 请求头从环境变量读取。

API Key 为什么必须当成密码

拥有有效 API Key 的人，可能在你的项目额度内发送请求，造成数据风险、异常费用和服务中断。

官方安全建议包括：不要共享个人密钥，不要把密钥部署到浏览器或移动端，不要提交到代码仓库，并使用环境变量或密钥管理服务。

macOS 或 Linux 当前终端可以临时设置：

export OPENAI_API_KEY="YOUR_REAL_KEY"

这条命令里的 YOUR_REAL_KEY 是占位符。真实值只应在你自己的受控终端中输入，不要放进文章、聊天、截图或仓库。

官方 SDK 通常能从 OPENAI_API_KEY 环境变量读取凭证。生产环境还要考虑密钥管理、权限分离、轮换和用量监控，不能只靠一条 shell 配置。

环境变量不是保险箱

把密钥放进环境变量，比硬编码进源码更安全，但它不代表密钥永远不可见。

同一用户下运行的进程、错误日志、调试工具、终端历史和恶意脚本仍可能接触它。真正的安全要同时控制：

• 谁能登录机器。
• 哪个进程能读取变量。
• 日志是否打印请求头。
• 第三方工具是否上传配置。
• 密钥权限是否过大。
• 泄露后能否快速撤销。

本地开发可以从环境变量开始，生产服务应根据风险考虑专门的密钥管理。

两种 Token 的区别

文本 Token：用于模型处理和计费

模型不会直接按“一个汉字”或“一个英文单词”理解全部文本，而会把输入分成 Token。输入、输出、缓存和不同能力的计费方式可能不同，必须以当前价格页为准。

同样字数的中文、英文、代码和 JSON，Token 数不一定相同。不能用“文章有一千字，所以一定是一千 Token”估算。

鉴权 Token：用于证明权限

OAuth Access Token、Session Token 或其他 Bearer Token 可能代表一个用户、应用或会话的访问权限。它通常具有作用域和有效期。

这类 Token 和模型文本计量没有关系。泄露后应按凭证处理，撤销、轮换并检查异常访问。

看到 Token 一词时，先看它出现在“usage”“input/output”附近，还是出现在“Authorization”“login”“OAuth”附近。

ChatGPT 网页与 API 不要默认共用计费

网页产品、开发者平台、组织、项目和 API 用量可能拥有不同的账户入口与计费规则。

不要因为自己能在网页聊天，就默认程序调用免费；也不要因为 API 有余额，就推断网页订阅包含相同权限。接入前分别检查当前官方产品说明和用量页面。

第一次调用前，先完成七项准备

1. 从官方文档确认当前 endpoint、SDK 和模型。
2. 在自己的官方项目中创建密钥。
3. 设置预算、限额或用量提醒。
4. 把密钥放进受控环境，不写入源码。
5. 使用无隐私的最小输入。
6. 关闭无限自动重试。
7. 准备查看状态码、响应体和用量记录。

不要用来历不明的共享账号、短信接码或低价中转完成第一次接入。它们会把技术问题变成账号、隐私、稳定性和合规问题。

怎样判断第一次调用真的成功

终端打印一段模型文字，只证明请求得到了某种响应。完整验收还要看：

• HTTP 请求发往预期官方地址。
• 响应是结构正确的 JSON。
• 返回内容与输入对应。
• 请求记在自己的项目下。
• 用量页面出现合理记录。
• 日志没有打印完整密钥。
• 程序没有在后台无限重试。
• 输入中没有不该离开本机的数据。

如果使用第三方 SDK 或代理，还要知道它是否改变 endpoint、保存请求或替换鉴权方式。

常见状态码应该怎样理解

400：请求本身有问题

检查 JSON 格式、必填字段、模型和参数。不要先创建新密钥。

401：身份无法确认

检查密钥是否来自正确项目、环境变量是否进入当前进程、值前后是否有空格，以及请求头格式是否正确。

密钥疑似泄露时，不要继续调试旧密钥，先撤销并轮换。

403：已经识别身份，但没有对应权限

检查组织、项目、模型或地区权限。不要把 403 一律解释成余额不足。

429：请求过多或额度受限

查看当前速率限制、余额和用量。重试需要退避和上限，不能无休止循环。

5xx：服务端暂时异常

保留请求时间和必要标识，使用有限重试。涉及会产生外部副作用的 API 时，还要考虑前一次请求是否其实已被处理。

网络错误和 API 错误不是一回事。前者可能没有拿到任何 HTTP 响应，后者通常带状态码和结构化错误。

费用怎样估算

最小成本模型可以写成：

总费用 =
  输入 Token 费用
  + 输出 Token 费用
  + 工具或媒体费用
  + 重试造成的额外请求

真实规则可能包含缓存、批处理、图片、音频或不同模型价格。文章中的数字很容易过期，使用当天应查看官方价格。

控制费用最有效的办法不只是缩短 Prompt，还包括：

• 限制最大输出。
• 避免把无关历史反复发送。
• 给循环设置次数上限。
• 记录每次任务的模型和用量。
• 先用最小请求验证，再扩大数据。
• 对用户输入设置长度边界。

密钥泄露后先做什么

1. 立即撤销或轮换密钥。
2. 检查当前与历史用量。
3. 查找密钥出现的位置。
4. 清理源码、日志、截图和部署配置。
5. 如果进入 Git 历史，按泄露处理，不只删除当前文件。
6. 检查程序是否仍引用旧密钥。
7. 为新密钥设置更小权限和预算。

不要先在群里询问“这串 Key 还能不能用”，那会造成第二次泄露。

第一次 API 调用结束后，别只保存那段模型回复。确认凭证属于谁、费用记到哪里、数据发往哪个地址。三个答案都清楚，再把调用接进自动化。