本指南涵盖的内容
本指南说明如何创建或登录 OpenAI 平台账户、添加付款方式、创建 Secret Key、发出第一次请求、查看用量,以及排查常见的 Key 错误。适合希望在自己的脚本或应用中调用 OpenAI API 的人。本指南不涉及 ChatGPT 订阅,那是另外计费的产品。
前提条件
- 账户: 一个你能控制并能找回的 OpenAI 登录方式。
- 付款: OpenAI 在你所在地区提供的付款方式或预付选项。可用方式因地区而异,我无法核实完整列表(UNKNOWN)。
- 基本的代码能力: 你应能打开终端、设置环境变量并运行简短脚本。示例使用
curl,以及配合 Node.js 的 JavaScript。
步骤 1:创建或登录 OpenAI 平台账户
打开 API keys 页面。按提示登录,或创建账户。请使用你本人拥有的账户。
如果你所在的组织已有 API 账户,请让组织所有者邀请你,而不是共享 Key。OpenAI 的 成员管理指南 对此有说明。
步骤 2:添加付款方式并了解按用量计费
打开 账单设置页面,该链接见于 OpenAI 的 错误参考。按页面提示添加付款方式或额度。
API 按用量计费。OpenAI API 定价页面 和 开发者定价参考 列出了费率。参考文档说明,除非另有标注,价格以每 100 万 token 计,并单独列出部分内置工具。开始前请查看你计划使用的模型的费率。本指南不列出具体价格,因为价格会变化且因模型而异。
如果预付余额用完,请求可能因 credit_balance_exhausted 错误而失败。请参阅下文的排查部分。
步骤 3:创建 Secret Key 并只复制一次
- 打开 API keys 页面。
- 创建新的 Secret Key,并命名为将使用它的应用或脚本。
- 立即复制该 Key,并保存到密码管理器中。OpenAI 的 API Key 帮助文章 指出,完整的 Secret Key 只会在创建时显示一次。如果丢失,请创建新 Key 并更新你的应用。已删除的 Key 无法再使用。
- 切勿将 Key 粘贴到聊天、截图或源代码中。
我无法读取 API keys 页面的文字内容,因此按钮名称可能与这里的步骤不同。
步骤 4:发出第一次 API 调用
将 Key 保存在环境变量中,使代码中永远不包含它。在 macOS 或 Linux 上,在终端中运行以下命令,并将占位符替换为你的 Key:
export OPENAI_API_KEY="your_api_key_here"
在 Windows PowerShell 中使用以下命令,然后打开新的终端窗口:
setx OPENAI_API_KEY "your_api_key_here"
用 curl 测试。将 MODEL_ID 替换为你的账户可用的模型:
curl "https://api.openai.com/v1/responses" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "MODEL_ID",
"input": "Say hello in one short sentence."
}'
对于 JavaScript,先运行 npm install openai 安装官方 SDK,然后将以下内容保存为 hello.mjs:
import OpenAI from "openai";
// The SDK reads OPENAI_API_KEY from the environment.
const client = new OpenAI();
const response = await client.responses.create({
model: "MODEL_ID",
input: "Say hello in one short sentence.",
});
console.log(response.output_text);
运行 node hello.mjs。开发者快速入门 使用的正是这一模式。如果出现错误,请前往排查部分。
步骤 5:查看用量
成功调用后,打开平台账户中的用量面板,确认该请求已出现。OpenAI 的 用量导出文章 介绍了 API Usage Dashboard。在那里你可以查看月度用量,并以 CSV 导出整个日历月或本月至今的用量或费用数据。如果请求尚未出现,请稍后再查看。我无法核实需要多长时间(UNKNOWN)。
可以免费使用 API 吗?
OpenAI 的定价页面描述的是按用量计费的费率。我无法从官方页面核实新账户是否获得免费额度或任何模型的免费层(UNKNOWN)。定价参考中有部分项目标为免费或包含免费额度,例如部分文件存储的 1 GB 免费额度,以及一个免费的内容审核模型。在假定任何调用免费之前,请查看当前定价页面中你所用模型和工具的说明。
如何保护 Key 的安全?
请遵循 OpenAI 的 API Key 安全最佳实践。具体做法:
- 切勿将 Key 提交到 git。 将 Key 保存在环境变量或本地密钥存储中,并将
.env文件加入.gitignore。每次推送前检查暂存的更改。 - 泄露后立即轮换。 如果 Key 出现在代码仓库、日志、截图或聊天中,请在 API keys 页面删除它,创建新 Key,并更新你的应用。已删除的 Key 将停止工作。
- 每个项目使用一个 Key。 为每个应用、脚本和团队成员分配各自的 Key。OpenAI 表示共享 API Key 违反其使用条款,因此请邀请队友使用各自的账户。
- 设置过期时间。 项目 Key 可以设置到期日期。请在旧 Key 到期前创建替代 Key,并在新 Key 运行正常后撤销旧 Key。
- 不要把 Key 发给支持团队。 任何支持渠道都不需要你的 Key。
为什么我的 Key 不能用?
请阅读状态码和错误信息,然后对照 OpenAI 的 错误参考 进行匹配。
| 状态码与信息 | 可能原因 | 处理方法 |
|---|---|---|
401 Incorrect API key provided | Key 错误、已删除,或来自其他账户 | 在 API keys 页面 检查 Key。确保代码中始终使用同一个 Key。参见 Incorrect API key provided。 |
401 You must be a member of an organization | 你的账户不在拥有该 Key 的组织中 | 请组织管理员邀请你。 |
401 IP not authorized | 请求来自允许列表之外的 IP 地址 | 从允许的 IP 发送请求,或更新允许列表。 |
429 Rate limit reached for requests | 短时间内请求或 token 过多 | 放慢请求速度;如有 Retry-After 响应头,请遵循其提示。参见 速率限制指南 和 429 排查文章。 |
429 credit_balance_exhausted | 预付额度已用完 | 在 账单设置 中添加额度。仅重试无法解决。 |
429 且错误类型为 insufficient_quota | 触发了与账单相关的限制 | 检查账单和任何用量限制,然后参阅 429 排查文章。 |
403 Country, region, or territory not supported | 从不受支持的地区访问 API | 查看错误参考所链接的 受支持国家和地区列表。 |
如果遇到此处未列出的信息,请在错误参考中搜索完全相同的文字。我无法核实每条 403 信息的完整含义(UNKNOWN)。
Cue 需要我自己的 OpenAI API Key 吗?
UNKNOWN。我查看了 Cue 的公开页面:heycue.io、定价 和 常见问题。页面列出了模型,但我读过的内容都没有说明 Cue 自身功能是否需要你的 OpenAI API Key。在依赖任何一种方式之前,请检查你的 Cue 设置和套餐说明。切勿把 API Key 发给 Cue 支持。
未验证或无法获取的项目
platform.openai.com/docs/quickstart发生跨域重定向,未被跟随。我改用developers.openai.com/api/docs/quickstart的 Markdown 版本。platform.openai.com/api-keys没有返回可读的页面文字。Key 步骤依据 OpenAI 的帮助文章,按钮名称未经核实。openai.com/api/pricing/在我的抓取中被截断。费率来自开发者定价参考。本文未列出任何价格。- 新账户的免费额度或免费层:UNKNOWN。
- 每条 403 信息的含义:除国家或地区这一情形外,均为 UNKNOWN。
- Cue 是否需要你自己的 OpenAI API Key:UNKNOWN。
Cue 是由 Sophon LLC 开发的独立桌面 AI 助手。 使用 Cue 处理你获得授权的文档、笔记和任务,可选择 Claude 与 GPT 模型。请查看 Cue 套餐说明,了解你的账户包含哪些内容及可用模型。你的 OpenAI 账户的 API Key、账单和用量仍由 OpenAI 管理。