很多人第一次调 OpenAI 卡住，不是代码写错，而是没搞明白「模型」和「API Key」是两回事：模型是你调哪个脑子，Key 是你凭什么进门。这篇按新手实际会遇到的顺序捋一遍，从认模型名到把 Key 放进环境变量、跑通第一条请求、再到限额是怎么回事。
很多人第一次调 OpenAI 卡住，不是代码写错，而是没搞明白一件事：模型和 API Key 是两码事。模型是你调哪个脑子，Key 是你凭什么进门。选错模型，结果不对；Key 配错，请求根本发不出去。这两件事常常被混在一起讨论，于是排查起来就乱。
这篇按新手实际会遇到的顺序捋一遍：先认清两者的分工，再学会看模型名字，然后从生成 Key 到写进环境变量，跑通第一条请求，最后搞明白额度和限速到底挂在谁身上。每一步都给可执行的检查动作，不空谈概念。
先分清：模型是商品，Key 是门票
模型决定这次请求的能力上限和计费口径，Key 只决定身份、权限和额度归属。换个说法：模型是你点了哪道菜，Key 是你有没有资格进这家餐厅。同一把 Key 可以调多个模型，换模型不需要换 Key；反过来，Key 泄露和模型选错是两个完全独立的问题，别指望用换 Key 解决模型能力不对。
- 一个账号可以开多把 Key，按项目或环境拆开，方便单独停用和查账
- Key 只做身份和权限校验，改不了模型本身的能力边界
- 模型选型是产品问题，Key 管理是工程安全问题，分开看才不会互相甩锅
- 额度按账号或项目算，不按 Key 算，所以多开 Key 并不会多出额度
OpenAI 模型系列怎么认名字
OpenAI 的模型大致按能力定位分几档：通用对话档适合大多数日常任务，轻量档主打低延迟和高并发，推理型档擅长需要多步思考的难题，多模态档则处理图像、语音等非纯文本输入。你不必背名字，但要知道自己这次任务落在哪一档，再去挑对应系列。
名字后缀有个容易踩的坑：带日期快照的名字是固定版本，不带日期、指向最新版的别名会随时间漂移。生产环境建议钉快照，避免某天后台更新导致输出风格突变；个人试验用别名无所谓。具体有哪些系列、各档当前的价格和上下文长度，到 /models 和 /official-api/providers/openai 看当时的数字，别照抄旧文章。
| 模型档位 | 典型任务 | 选型关注点 |
|---|---|---|
| 通用对话档 | 问答、写作、摘要 | 综合能力与输出稳定性 |
| 轻量高并发档 | 分类、抽取、批量处理 | 单位成本与响应速度 |
| 推理型档 | 多步计算、复杂判断 | 是否值得为准确率多花时间 |
| 多模态档 | 看图、语音转写 | 输入类型是否被支持 |
一把 Key 从生成到落地的完整动作
Key 在账号后台创建，创建后只显示一次，关掉页面就再也看不到。所以第一件事不是写代码，而是立刻把它存进密码管理器或团队的密钥服务，别留在聊天记录和便签里。
- 创建并就地保存在后台新建 Key，复制后马上存入密码管理器；验证方法：下次需要时从管理器取，而不是到处翻记录
- 放进环境变量本地开发写到环境变量或 .env 文件，并确认 .env 已在 .gitignore 里；验证方法：在仓库里搜一遍 Key 开头字符，搜不到才算干净
- 按人按项目分发团队里每人每项目一把独立 Key，不用共享同一把；验证方法：停用某把 Key 后，只有对应项目报错，其他项目不受影响
- 配置检查顺序环境变量是否被程序读到 → 项目归属和权限是否够 → 余额或额度是否还有；这三步按顺序走，别跳步
# 临时设置环境变量，仅当前终端会话有效
export OPENAI_API_KEY="你的key"
# 验证程序能读到（不打印完整值）
printenv OPENAI_API_KEY | head -c 8跑通第一条请求的最小步骤
装好官方 SDK 后，让代码从环境变量读 Key，不要硬编码在脚本里。第一次请求别上来就发长文，用一条短提示、把输出长度调小，先确认能连通。连通性没问题，再逐步加长、加复杂度，出问题时才容易定位。
- 401 报错：多半是 Key 无效、拼错，或程序根本没读到环境变量
- 429 报错：多半撞到限速或额度上限，换 Key 不解决
- 模型名报错：回去核对模型标识写法，别名和快照名不要混用
- 拿不准延迟基线时，先到 /tools/speed-test 量一遍自己到接口的网络往返
- 同一段代码换机器就失败，优先怀疑那台机器没配环境变量
| 现象 | 优先怀疑 | 下一步动作 |
|---|---|---|
| 401 未授权 | Key 无效或未被读到 | 打印环境变量长度确认存在，再核对 Key 是否正确 |
| 429 限流 | 请求过密或额度耗尽 | 降并发、缩短输出，去后台看额度状态 |
| 模型不存在 | 模型标识写错 | 回 /models 对照当时的可用标识 |
| 请求超时 | 网络或代理问题 | 先跑速度测试，再排查代理配置 |
额度、限速和费用怎么对应到 Key
额度是按账号或项目算的，不按 Key 算，所以超额了换多少把 Key 都没用，得回到账号或项目层面看。限速通常分两条线：一分钟请求数和一分钟 token 数。短请求发得密，容易撞请求数那条；长文本少发几次，也可能撞 token 数那条。判断自己撞了哪条，比盲目加重试有用。
费用跟模型档位以及输入输出比例有关，同样的字数，不同档位差别不小。想估算，可以用 /tools/token-price-calculator 和 /tools/model-cost-calculator 按当时口径折算。价格和套餐会调整，具体数字到 /price-watch 和 /official-api 核对，别拿旧文章的截图当依据。这套判断只适用于按量计费的常规调用；如果你走的是企业协议或特殊通道，口径可能不同，以合同和后台说明为准。
Key 管进门，模型管干活，额度管你还能干多久——三件事分开放，问题一眼就能归位。下一步把模型档位和当前价格口径对一遍，再决定这次任务用哪档模型。→
常见问题
有了 API Key 就能用所有 OpenAI 模型吗？
不一定。Key 决定你有没有调用资格，能不能调某个模型还看账号所在项目、是否开通对应权限、有没有余额。换 Key 通常解决不了「这个模型用不了」，先查权限和额度，再查模型标识是否写对。
API Key 会不会过期，要不要定期换？
默认不会自动过期，所以更该主动管理：按项目拆多把 Key，泄露或人员离职时单独撤销，不用把整账号的 Key 全换。撤销后旧 Key 立即失效，生产环境要预留替换窗口。
本地调试正常，上线就报 401 或 429，先查什么？
401 先看服务器环境变量是否真的注入了 Key；429 先区分是限速还是额度见底，两条线的处理方式不同。跨地区调用还可能被网络层拦，先用最小请求在目标环境单独验证一次。
