OpenAI Codex API 入门：从 API Key 到第一条代码请求
简答：OpenAI Codex API 不是一个独立的“Codex 专用接口”，而是通过 OpenAI API 的 Responses API 调用面向编程任务优化的 Codex 模型。最短路径是：创建项目 API Key，保存为环境变量，先用当前模型列表核验可用模型，再向 /v1/responses 发送包含 model 和 input 的请求。本文示例使用官方文档当前列出的 gpt-5.3-codex，但该模型截至 2026 年 10 月 31 日已标记为 Deprecated，生产环境应以模型列表和迁移公告为准。
定义：OpenAI Codex API 指通过 OpenAI Responses API 调用 Codex 优化模型，以完成代码生成、解释、调试、审查和代理式编程任务的接入方式。
先看结论：Codex API、Responses API、Agents API 和 CLI 怎么区分
本文是第三方 AI API 接入指南，不代表 OpenAI 官方。Codex 更接近一组面向代码和代理式编程的模型与开发资源；真正发送模型请求时，主要使用 Responses API。OpenAI 文档明确说明，GPT-5.3-Codex 可通过 Responses API 直接调用，并支持编程代理场景。可先阅读Responses API 参考和Codex 模型使用指南。
| 名称 | 作用 | 适合什么场景 |
|---|---|---|
| Codex 模型 | 负责理解和生成代码 | 代码生成、重构、调试、审查 |
| Responses API | 发送输入并获取模型响应 | 自建应用、脚本、后端服务 |
| Agents API | 提供托管的 Codex harness、会话、编排和沙箱能力 | 需要长任务、工具调用、文件操作和会话恢复的代理应用 |
| Codex CLI | 命令行开发工具或参考实现 | 本地代码仓库中的交互式编程工作流 |
Agents API 的定位不同于一次普通模型请求：官方说明它可以管理会话、编排、上下文压缩和恢复，并让代理在沙箱中执行代码、编辑文件或连接 MCP。若你只是想从 Python、JavaScript 或后端服务发出一条代码请求，先使用 Responses API 更容易定位问题。
创建 API Key，并确认模型 ID 不要写错
- 打开OpenAI API Keys 控制台，登录后选择或创建项目，再创建项目 API Key。
- 把 Key 放到服务端环境变量中，不要写入前端网页、移动端应用、Git 仓库或截图。OpenAI API 参考要求使用 Bearer 认证，并建议从环境变量或密钥管理服务加载 Key。
- 先列出当前账号可用模型：
curl https://api.openai.com/v1/models -H "Authorization: Bearer $OPENAI_API_KEY"。 - 截至 2026 年 10 月 31 日，OpenAI 当前 Codex 资料仍列出
gpt-5.3-codex，但模型页面已标记为 Deprecated，并显示计划在 2027 年 4 月 1 日移除；因此本文把它作为可核验示例，不建议不经检查就硬编码到长期生产配置。
可在终端设置环境变量：export OPENAI_API_KEY="你的_API_Key"。PowerShell 可使用：$env:OPENAI_API_KEY="你的_API_Key"。如果命令返回 401，先检查变量是否为空、Key 是否复制完整，以及请求是否真的发送了 Authorization: Bearer。
官方认证说明、项目与请求调试字段见API Reference Overview；其中还列出了 x-request-id 和速率限制响应头，可用于后续排错。
第一条 Codex API 请求：curl、Python 和 JavaScript
下面的最小请求使用 POST https://api.openai.com/v1/responses，请求体只保留 model 和 input。成功判定不是“命令没有报错”，而是 HTTP 状态码为 2xx，并且响应中存在可读取的输出内容。若你的模型列表中没有 gpt-5.3-codex，请把 MODEL_ID 替换为当前账号实际可用的模型。
curl：curl https://api.openai.com/v1/responses -H "Authorization: Bearer $OPENAI_API_KEY" -H "Content-Type: application/json" -d '{"model":"gpt-5.3-codex","input":"请解释下面这段 Python 代码的作用，并指出一个潜在问题：\n\nprint(\"hello\")"}'
Python：import os, json, urllib.request
payload = {"model": "gpt-5.3-codex", "input": "请生成一个带输入校验的 Python 函数，并说明测试方法。"}
req = urllib.request.Request("https://api.openai.com/v1/responses", data=json.dumps(payload).encode(), headers={"Authorization": f"Bearer {os.environ['OPENAI_API_KEY']}", "Content-Type": "application/json"}, method="POST")
with urllib.request.urlopen(req, timeout=60) as r:
data = json.load(r)
print(json.dumps(data, ensure_ascii=False, indent=2))
JavaScript：const response = await fetch("https://api.openai.com/v1/responses", { method: "POST", headers: { "Authorization": `Bearer ${process.env.OPENAI_API_KEY}`, "Content-Type": "application/json" }, body: JSON.stringify({ model: "gpt-5.3-codex", input: "审查这段代码的边界条件，并给出最小修复建议。" }) });
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
console.log(await response.json());
代码示例只展示最小调用，不代表所有工具参数都能直接套用。需要流式输出时，再根据Responses API 的流式事件文档处理事件；首次排错建议先关闭流式，确保普通 JSON 请求能够成功。
请求参数怎么选：model、input、instructions、tools 和 stream
| 参数 | 用途 | 入门建议 |
|---|---|---|
model | 指定模型 ID | 先从 /v1/models 或官方模型页复制，不要凭记忆填写 |
input | 用户问题、代码或多轮输入 | 先使用字符串，复杂会话再使用结构化输入 |
instructions | 提供全局任务约束和行为要求 | 适合规定代码风格、输出格式和安全边界 |
tools | 接入函数、搜索、代码执行等工具 | 确认模型和账号支持后逐项增加 |
stream | 以事件流方式接收输出 | 先用非流式请求验证 Key、模型和请求体 |
适合直接调用模型的情况是：你已经有自己的应用、工具编排和代码执行环境，只需要模型输出。若需要 OpenAI 管理会话、沙箱、工具和恢复逻辑，可以进一步研究Agents API 概览。如果目标是本地仓库中的交互式命令行工作流，则应单独评估 Codex CLI，而不是把 CLI 登录方式和 API Key 认证混为一谈。
用于代码任务的提问最好包含输入前提、目标、限制和验收方式。例如：这是一个 Python 3.12 项目，入口文件为 app.py。请只修改输入校验部分，保持函数签名不变，先列出风险，再给出补丁，最后提供 3 个测试用例。人工复核点包括：是否真的遵守文件范围、是否引入未声明依赖、测试是否覆盖异常输入、生成的修改是否需要人工审查。
模型、价格与生产环境检查
官方模型页显示，GPT-5.3-Codex 的上下文窗口为 400,000，最大输出为 128,000 token，并支持推理强度设置；但同一页面当前已标记该模型为 Deprecated。价格也会随模型、缓存输入、区域处理和政策变化，本文不把旧价格当作长期承诺。请在部署前查看OpenAI API Pricing和当前模型页面。
计费通常按输入 token、缓存输入 token 和输出 token 计算，工具还可能产生额外费用。Responses API 本身不是单独收取一笔“接口费”，最终应按所选模型和已使用工具的官方价格核算。不要用“一个请求固定多少钱”估算项目成本，应该记录实际 token 用量并设置预算或告警。
- 密钥：只放在服务端；前端调用应经过自己的后端，不要把长期 Key 暴露给浏览器。
- 超时：为 HTTP 客户端设置合理超时，超时后不要无条件重复提交可能产生副作用的工具任务。
- 重试：对 429 和部分临时 5xx 使用指数退避；对 401、403、404 先修配置，不要重复重试。
- 日志：记录状态码、模型、耗时、脱敏后的请求摘要以及响应头中的
x-request-id，不要记录完整 API Key。 - 模型变更：使用模型列表、模型页和弃用公告定期复核，必要时使用固定快照并配套回归测试。
401、403、404、429 和超时：按请求链路排查
- 401：确认 API Key 是否为空、是否过期或撤销、Bearer 拼写是否正确；也要检查环境变量是否只在另一个终端窗口中设置。
- 403：确认项目权限、组织或区域限制，以及当前 Key 是否有权调用该模型。不要把 403 直接判断为模型不存在。
- 404：先打印最终请求地址，确认是
/v1/responses而不是拼接了重复的/v1；再检查模型 ID 是否来自当前模型列表。 - 429：读取响应头中的请求和 token 限制，降低并发、缩短输入、使用退避重试，并确认项目预算和限额。
- 超时或流式中断：先改用非流式最小请求；再检查代理、网关、客户端超时和响应读取逻辑。若收不到服务端 request ID，可设置自己的
X-Client-Request-Id做链路关联。
排错顺序应固定为：Key → Base URL → 实际路径 → model → 请求体 → 权限/限额 → 网络与流式处理。每次只改一个变量，并保留 HTTP 状态码和脱敏日志，这样才能判断问题来自官方直连、兼容网关还是客户端 SDK。
常见问题
OpenAI Codex API 和 ChatGPT 订阅是同一个东西吗？
不是。Codex API 使用 OpenAI Platform 的 API Key 和 API 计费；ChatGPT 或 Codex 客户端中的登录、订阅和 API 项目额度不能默认视为同一套认证。实际权限和计费以对应产品的官方页面为准。
现在还能直接使用 gpt-5.3-codex 吗？
截至 2026 年 10 月 31 日，官方模型页仍列出该模型，但已标记为 Deprecated，并有后续移除安排。调用前应通过 /v1/models 检查账号可见性，并查看官方迁移建议；不要把它当作永不过期的模型 ID。
为什么我的 Codex API 请求返回 404？
最常见的核验点是请求路径、Base URL 和模型 ID。确认使用 /v1/responses，确认没有重复拼接 /v1，并从当前模型列表复制 model 字段；如果仍失败，再检查项目权限和网关是否改写了路径。
Responses API 一定要使用 stream 吗？
不一定。首次接入建议先使用非流式请求，确认能得到完整 JSON 后再启用 stream。流式模式需要正确消费事件，客户端过早关闭连接也可能看起来像模型或网络故障。
可以把 API Key 直接放进 Cursor、网页或浏览器脚本吗？
不建议把长期 API Key 放到浏览器、移动端或公开代码中。更安全的方式是由服务端保存 Key，再由服务端调用 API；日志、错误上报和前端配置中也应脱敏。