OpenAI API 使用教程：API Key、首次调用与常见错误

从创建 API Key、配置环境变量到用官方 SDK 完成第一次调用，讲清 OpenAI API 的认证方式、请求地址、token 计费逻辑与 401、429、超时等常见错误的处理办法。

OpenAI API 是什么

它是 OpenAI 对外提供的模型调用接口：你的程序发一个 HTTP 请求过去，带上要用的模型和输入内容，接口把模型的输出返回给你。ChatGPT 是给人用的产品，API 是给程序用的入口——同一批模型，两种使用方式。

用它的理由通常只有一个：你要把模型能力放进自己的产品里，而不是自己坐在网页前提问。

ChatGPT 订阅和 API 是两回事

这是新手最常踩的坑，值得单独说清楚。

	ChatGPT 订阅	OpenAI API
面向	人	程序
入口	网页、桌面端、移动端	HTTP 接口与官方 SDK
计费	按月订阅	按 token 用量
账单	独立	独立

订阅不包含任何 API 额度。 开了 ChatGPT Plus 之后去调 API，一样会因为没有付款方式或额度而失败。两套系统各有各的付款方式和账单页面，互不相通。

开始之前

三件事：

• 一个 OpenAI Platform 账号，并且已经添加付款方式或充值了预付额度。
• 确认所在地区在官方支持范围内，否则请求会返回地区不支持的错误。
• 一个能跑代码的环境：Python 或 Node.js 都行；只想验证链路的话，有 curl 就够了。

创建 API Key

在 OpenAI Platform 控制台的 API keys 页面新建密钥。两个细节：

1. 按用途命名。 「本地调试」「生产后端」「某个脚本」各自一把，出问题时可以只撤销受影响的那一把。
2. 创建后立刻保存。 密钥只完整显示一次，页面关掉就再也看不到，唯一的补救是重新生成一把新的。

保存位置应该是密码管理器或密钥管理服务，不是备忘录，也不是聊天记录。

密钥安全的底线

• 不写进源码、配置文件、截图、issue、聊天记录。
• 不放进前端 JavaScript、移动端 App 或任何用户能拿到的产物。
• 不提交到任何仓库，公开仓库尤其致命——公开仓库里的密钥会在几分钟内被扫走。
• 不发给不可信的第三方服务。

一旦怀疑泄露，处理顺序是撤销 → 重建 → 查用量 → 排查泄露路径，先止损再复盘。完整的轮换与泄露处置流程见 OpenAI API Key 获取与安全管理。

把密钥放进环境变量

代码里永远只读环境变量，不出现密钥本身。

macOS 与 Linux：

export OPENAI_API_KEY="你的密钥"

Windows：

setx OPENAI_API_KEY "你的密钥"

setx 写入的是持久环境变量，设置后要重开终端才会生效。这一步没做，程序读到的是空值，表现出来就是 401。

认证与请求地址

两个基础概念，理解了就不会在文档里迷路。

Endpoint（接口地址） 是你要请求的具体 URL。基础地址是 https://api.openai.com/v1，不同能力对应不同路径，比如文本生成走 /v1/responses。

Authentication（认证） 用 HTTP 请求头传递，形式是：

Authorization: Bearer 你的密钥

官方 SDK 会自动帮你拼这两样东西，所以正常情况下你不需要手写。但知道它们的存在很重要——排查 401 的时候，问题几乎总在这两行里。

顺带一提，SDK 支持通过 base_url 参数或 OPENAI_BASE_URL 环境变量改写基础地址。官方场景下你用不到它，但它是第三方 API 中转服务能「无缝兼容」的技术前提。

安装官方 SDK

Python：

pip install openai

Node.js：

npm install openai

两个 SDK 都会默认读取 OPENAI_API_KEY 环境变量，所以创建客户端时不需要传任何密钥参数。

第一次请求

先用 curl 确认链路通畅：

curl "https://api.openai.com/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-6-astra",
    "input": "用一句话解释什么是 API。"
  }'

Python：

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-6-astra",
    input="用一句话解释什么是 API。",
)

print(response.output_text)

Node.js：

import OpenAI from "openai";

const client = new OpenAI();

const response = await client.responses.create({
  model: "gpt-6-astra",
  input: "用一句话解释什么是 API。",
});

console.log(response.output_text);

三段代码做的是同一件事：指定模型、给一段输入、拿到输出。OpenAI() 不传参数，是因为它自己去读环境变量了。

模型名会变。 上面用的是官方快速开始文档当前给出的模型，写代码时请到官方模型页面确认当前可用的名称，不要照抄旧文章里的模型名——模型下线之后，请求会直接报错。

Responses 还是 Chat Completions

你会在文档和网上教程里看到两种接口形态：

• Responses API：官方对新项目推荐的统一接口，也是内置工具能力（网页检索、文件检索、代码解释器等）的落点。
• Chat Completions：更早的接口形态，仍然受支持，生态里的老代码大量使用它。

结论很简单：新项目从 Responses 开始；已有项目跑得好好的不必为了迁移而迁移。看到教程里用 messages 数组的，那是 Chat Completions 的写法，不是错的，只是不是新项目的默认选择。

理解 model 参数

model 决定了三件事：能力上限、响应速度、单价。选型时的实际做法是：

• 先用能力较强的模型把功能跑通，确认效果满足需求。
• 再往下试更小、更快、更便宜的模型，看效果是否仍然可接受。
• 对延迟敏感的场景（比如输入框的实时补全）优先考虑小模型。

本文不列价格表。 模型和单价变动频繁，任何写死在文章里的价格都会过期。需要具体数字时看官方定价页面，那是唯一可靠的来源。

Token 与成本

token 是模型处理文本的基本单位，也是计费单位。三条实用结论：

1. 输入和输出分别计价，通常输出比输入贵。
2. 多轮对话的成本不是线性的。 每一轮请求都要把之前的历史消息重新作为输入发一遍，对话越长，单轮成本越高。
3. 控制成本最直接的两个手段是裁剪送进去的历史，以及限制输出长度。

一个常见的账单事故就是：做了个聊天机器人，没有做历史裁剪，用户聊了两百轮，每一轮都在为前面一百九十九轮付费。

常见错误怎么读

接口用状态码 + 错误类型描述问题，先看状态码定大类，再看错误类型定具体原因。

状态码	常见含义	该做什么
401	密钥无效、过期或被撤销；密钥不正确	检查请求头格式与密钥本身，确认程序真的读到了环境变量；必要时重新生成
403	所在国家或地区不受支持	核对官方支持地区，属于账号与地区限制
429	限流，或额度、消费上限用尽	先分清是哪一种，两者处理方式完全不同（见下）
500	服务端内部错误	稍等重试，并查看官方状态页
503	模型容量暂时不足	按 Retry-After 等待重试；没有该头就自行拉长退避间隔

429 的两副面孔

这是最容易误判的一个。

限流类：短时间内请求数或 token 数超过了账户上限。它是暂时的，等一会儿就好，正确做法是按 Retry-After 等待并做指数退避。

额度类：预付额度用完，或触及了组织、项目层面的消费与用量上限。它不会自己恢复，重试一万次也没用，必须去账单页充值或调整限额。

判断方法是看响应体里的错误类型。看到余额耗尽、消费上限、用量上限一类的描述，就别再重试了。

限流与重试

限流用几个维度同时衡量，先撞到哪个就按哪个限：

• RPM / RPD：每分钟、每天的请求数
• TPM / TPD：每分钟、每天的 token 数
• IPM：每分钟图像数（图像类接口）

额度随累计消费自动升级用量层级。当前上限可以在账号的限制页面看到。

每次响应还会带上限流相关的响应头，包含剩余请求数、剩余 token 数与重置时间，遇到 429 时还会有 Retry-After 告诉你该等多久。生产环境里应该读这些头，而不是靠猜。

重试策略只需要记住两点：指数退避，以及加一点随机抖动。后者是为了避免多个客户端在同一时刻集体重试，把一次限流放大成一场雪崩。

官方 SDK 默认已经内置了针对连接错误、408、429 与 5xx 的自动重试，可以按需要调整重试次数和超时时间，不必自己从零实现。

用量与账单

上线之后要做的三件事：

1. 设置消费限额。 这是防止代码 bug 或密钥泄露把账单打穿的最后一道闸。
2. 定期看用量明细。 按密钥、按项目区分，能快速定位是哪部分在花钱。
3. 把用量异常当成安全信号。 用量突然增长而业务量没变，先怀疑密钥泄露，而不是先怀疑统计错了。

数据会被拿去训练吗

按官方说明，通过 API 发送的数据默认不用于训练或改进模型，除非你主动选择共享。出于滥用监控的需要，请求日志会保留一段时间；有合规要求的团队可以进一步了解官方的零数据保留方案。

这一点和消费级产品的默认策略不同，接入前值得向法务或安全同事说明清楚。

下一步

• 密钥怎么管：OpenAI API Key 获取与安全管理
• 换一家官方接口：Anthropic API 快速上手，认证与计费思路相通，接口形态不同
• 听说过 API 中转：API 中转站是什么？和官方 API 有什么区别
• 看看还有哪些接口可选：AI API 目录
• 想直接用现成的编程智能体而不是自己写调用代码：Codex 完整使用教程

参考资料

• API 快速开始（官方文档）
• 错误代码参考（官方文档）
• 限流说明（官方文档）
• API 数据使用说明（官方文档）
• ChatGPT 与 API 平台的计费区别（官方帮助中心）