OpenAI Image API 教程：Images API 和 Responses API 该怎么选

截至 2026 年 3 月 22 日，最稳的默认路线是：如果你要做的是直接生成图片或编辑图片，先用 Images API；只有当图片生成只是更大多模态工作流中的一个工具时，才切到 Responses API。 真正让这个关键词变复杂的，不是 SDK 语法，而是很多页面没有先讲清楚这一步。

这个搜索词之所以一直让人觉得“官方文档看了还是乱”，是因为 OpenAI 把答案分散在了多个页面里。主 图像生成指南 讲的是直接生成和编辑；更广的 Images and vision 指南 展示的是 Responses API 里的 image_generation 工具；当前 模型目录 又说明现在的图像家族已经是 GPT Image 1.5 主线、gpt-image-1-mini 低成本路线、chatgpt-image-latest ChatGPT 别名，以及已经标成 deprecated 的 DALL-E 3。如果你只看其中一页，拿到的通常只是局部真相。

多数教程的问题也出在这里。它们要么继续沿用 DALL-E 时代的思路，要么一上来就给你代码，却不先确认你的账户是不是已经在支持的 tier 上、组织验证是不是还没传导完成、当前应该用的是 Images API 还是 Responses API。本文的目标不是把参数堆满，而是把正确顺序讲清楚。

要点速览

• 直接出图、单步编辑、最短上手路径：先用 Images API。
• 图片生成只是更大助手工作流中的一个工具：再用 Responses API。
• 默认模型先从 gpt-image-1.5 开始；如果预算是第一约束，再去基准测试 gpt-image-1-mini。
• 如果教程示例看起来没问题但你仍然报错，优先检查 tier、组织验证、当前组织上下文和 API key，不要先怀疑 prompt。

先决定路线：Images API 还是 Responses API

如果你只记住这一节，也足够把大多数错误路线避开。当前 OpenAI 图片栈最关键的不是“哪个接口更新”，而是“你今天做的这个任务到底属于哪一类”。

实用规则很简单：如果图片生成本身就是功能主体，就先用 client.images.generate() 或 client.images.edit()；如果图片生成只是更大工作流里的一个工具，再改用 client.responses.create()。

OpenAI 官方文档其实已经给出了这两个方向，只是放在不同页面里。对于官方参考页来说没问题，但对“教程”来说，这会让读者自己去拼图。所以这篇文章的第一价值不是再抄一次代码，而是帮你先把路选对。

还有一个原因让这一步必须提前做：两条路线遇到的失败点并不一样。很多人说“OpenAI Image API 教程跑不通”，真正的问题往往不是 SDK，而是他其实该先排查账户访问、组织验证、模型命名，或者根本不该从 Responses API 起步。

写代码前先确认访问前提和模型 ID

在复制任何示例之前，先把这几个前提条件过一遍。很多所谓“教程失效”，本质上是把应该先确认的访问问题留到了最后。

先看当前模型。OpenAI 的现行模型目录把图像家族大致分成下面几条：

这一步重要，是因为搜索结果里仍然有很多旧页面把 GPT Image 1 或 DALL-E 3 当成主线。如果你拿它们当默认认知，教程从一开始就会偏。

再看访问条件。当前 API Model Availability by Usage Tier and Verification Status 页面明确写着，GPT-image-1 和 GPT-image-1-mini 面向 Tier 1 到 Tier 5 的 API 用户开放，部分访问还受组织验证影响。而当前 GPT Image 1.5 模型页 也写明了 Free not supported，并给出 Tier 1 从 100,000 TPM 和 5 IPM 起步。这意味着你完全可能在代码还没发挥作用之前就被挡住。

如果你怀疑是组织验证问题，就不要继续改 prompt。OpenAI 当前 API Organization Verification 的建议是：确认当前组织、等待最多 30 分钟、生成新的 API key、刷新会话，再重新测试。 这是访问分支，不是语法分支。

SDK 安装本身反而最简单。Node.js：

bash
npm install openai

Python：

bash
pip install openai

然后设置 OPENAI_API_KEY。第一条请求尽量保持简单：1024x1024、单张图、短 prompt、不要一开始就做多图编辑或透明背景复杂资产。官方指南明确说了，方图是默认尺寸，也是最快的起点。教程第一步应该追求“最容易定位问题”，而不是“功能一次拉满”。

用 Images API 跑通第一张图

如果你的目标是一个直接教程，Images API 仍然是最好的起点。原因不是它更“老”或更“原始”，而是它的心智模型更清楚：你明确选一个图像模型，明确设置输出参数，然后把返回的图片数据保存下来。

下面这个 JavaScript 例子，就是我会给大多数开发者的最小可运行路径：

js
import fs from "fs";
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

const result = await client.images.generate({
  model: "gpt-image-1.5",
  prompt: "Create a clean editorial illustration of a robot camera operator in a bright studio",
  size: "1024x1024",
  quality: "medium",
  output_format: "jpeg",
  output_compression: 80,
});

const imageBase64 = result.data[0].b64_json;
const imageBytes = Buffer.from(imageBase64, "base64");
fs.writeFileSync("openai-image-api-demo.jpg", imageBytes);

Python 版本同样很直接：

python
from openai import OpenAI
import base64

client = OpenAI()

result = client.images.generate(
    model="gpt-image-1.5",
    prompt="Create a clean editorial illustration of a robot camera operator in a bright studio",
    size="1024x1024",
    quality="medium",
    output_format="jpeg",
    output_compression=80,
)

image_base64 = result.data[0].b64_json
image_bytes = base64.b64decode(image_base64)

with open("openai-image-api-demo.jpg", "wb") as f:
    f.write(image_bytes)

这个起步示例有三个优点。第一，它明确使用当前主线模型 gpt-image-1.5。第二，它把尺寸和质量保持在好判断的范围内。第三，它让你立刻理解返回值处理，而不是依赖旧教程对 URL 输出的想象。

一旦第一张图成功，再进入编辑分支。当前官方指南也给了 Images API 的编辑示例，包括多图输入和 input_fidelity。如果你的目标是更贴近输入图的编辑，而不是“只要大致风格像就行”，input_fidelity: "high" 是现在最值得记住的参数之一。

js
import fs from "fs";
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

const result = await client.images.edit({
  model: "gpt-image-1.5",
  image: [
    fs.createReadStream("woman.jpg"),
    fs.createReadStream("logo.png"),
  ],
  prompt: "Add the logo to the woman's jacket as if stitched into the fabric.",
  input_fidelity: "high",
});

const imageBase64 = result.data[0].b64_json;
fs.writeFileSync(
  "woman-with-logo.png",
  Buffer.from(imageBase64, "base64")
);

这里最重要的不是记住所有参数，而是记住顺序：先让简单生成稳定成功，再去做编辑。 如果你第一条请求就是多图编辑、透明背景、复杂比例再加上验证还没传导完，那么你根本不知道到底是哪一层出了问题。

什么时候应该改用 Responses API

Responses API 不是“更高级所以默认更好”，它更适合的是图片生成只是更大工作流里的一步。这也是为什么 OpenAI 当前官方示例会在 responses.create() 里，用一个通用文本模型挂上 image_generation 工具。

JavaScript 官方思路大致是这样：

js
import fs from "fs";
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

const response = await client.responses.create({
  model: "gpt-5",
  input: "Draw a transparent sticker-style icon of a paper airplane for a travel app",
  tools: [
    {
      type: "image_generation",
      background: "transparent",
      quality: "high",
    },
  ],
});

const imageBase64 = response.output
  .filter((item) => item.type === "image_generation_call")
  .map((item) => item.result)[0];

fs.writeFileSync("paper-airplane.png", Buffer.from(imageBase64, "base64"));

Python 版本也一样：

python
from openai import OpenAI
import base64

client = OpenAI()

response = client.responses.create(
    model="gpt-4.1-mini",
    input="Generate a product hero image of a ceramic mug on a white background",
    tools=[{"type": "image_generation"}],
)

image_data = [
    output.result
    for output in response.output
    if output.type == "image_generation_call"
]

if image_data:
    with open("mug.png", "wb") as f:
        f.write(base64.b64decode(image_data[0]))

什么时候它比 Images API 更合理？通常是下面几类：

• 图片生成只是会话中的一个步骤
• 你还需要文字、工具调用或别的输出一起返回
• 你希望把图片作为更大代理流程的一部分，而不是一个独立功能

如果你的需求只是“生成一张图然后保存”，它反而会让教程一开始更难懂。因为你此时面对的不只是图片参数，还有工具输出解析、会话上下文和更大的 orchestration 语义。

还有一个容易过时的时间点要记住。OpenAI changelog 写明，2025 年 12 月 19 日，OpenAI 把 gpt-image-1.5 和 chatgpt-image-latest 加进了 Responses API 的 image generation 工具支持里。所以旧文章里那种“Responses 支持还没来”的说法，只能代表当时，不代表现在。

真正会影响结果和成本的参数

当第一张图已经成功，下一步不该是把所有高级参数一起打开，而是弄清楚哪些设置真的会改变结果、延迟或成本。

当前图像生成指南里最值得记住的是这几类：

• size
• quality
• background
• output_format
• output_compression
• input_fidelity

最实用的理解方式不是背参数名，而是看它们改变什么决策。

尺寸 同时影响构图和成本。第一次测试先用 1024x1024。官方指南明确说了，默认尺寸就是这个，方图也是最快的起步。只有当构图真的需要时，再去用 1536x1024 或 1024x1536。

质量 同时影响延迟和费用。当前 GPT Image 1.5 模型页里，1024x1024 low 是 $0.009，medium 是 $0.034，high 是 $0.133。这个差距已经足够大了，所以原型、烟雾测试、流程验证阶段没有必要默认 high。

背景 在你做透明素材时才重要。当前指南写得很清楚，GPT Image 家族支持 background: "transparent"，但这只适用于 PNG 和 WebP。而且透明背景在 medium 或 high 下通常更稳。如果教程没有提前说这一点，很多人会把“透明背景效果不好”误判成模型问题。

输出格式 和 压缩 决定的是文件形态与速度。当前指南说明，Image API 返回的是 base64 编码图片数据，默认格式是 PNG，你也可以请求 JPEG 或 WebP。如果你的第一约束是速度，JPEG 往往比 PNG 更实用。

input_fidelity 则是编辑特有的成本杠杆。它不适合被塞进“第一张图”示例里，但非常适合在教程后半段明确告诉读者：你要的是更贴近原图的编辑，还是更自由的再创作。

最稳的做法始终是：一次只改一个变量。不要同时改模型、尺寸、质量、背景、输出格式和编辑输入。否则你根本分不清结果变化是来自哪个决定。

如果你当前的问题已经从“怎么调通”变成“这样跑一个月要多少钱”，下一步更适合看中文版的 OpenAI 图像生成 API 定价。

这些失败分支，多数教程不会提前讲

这个关键词最容易浪费时间的地方，不是代码块，而是故障分支。很多教程只展示 happy path，却默认如果你失败了，应该是你抄错了示例。这个话题不是这样。

先说 403 验证错误。如果错误明确提到组织验证，就先停下，不要继续改 prompt 或 SDK。当前 OpenAI 帮助中心的建议是：确认正确组织、等待最多 30 分钟、创建新的 API key、刷新会话再测试。社区里有很多案例是仪表盘已经显示 verified，但 Images Playground 仍然拦住你。这不是代码问题，而是访问上下文问题。

再说 看起来已经充值却仍然 429。这是这个主题里最容易误判的点之一。Developer Community 里已经有多个帖子显示，用户明明加了 credits，甚至已经验证组织，仍然会在图像模型上看到 rate_limit_exceeded。真正该确认的是 usage tier，而不是只看余额。

然后是 编辑失败、mask 问题和旧教程对输出的错误预期。当前官方指南明确说了，编辑图和 mask 必须同格式、同尺寸，而且小于 50MB。如果你在 edit 路线里跳过这些条件，错误看起来会非常随机。

还有一个更隐蔽的问题：很多旧教程默认你会拿到一个托管 URL，然后围绕它写后处理。但当前 Image API 对 GPT Image 路线的主流返回方式是 base64 图片数据。如果你整个后处理链还建立在旧 URL 假设上，就算请求成功，后续也会错。

如果你怀疑问题不是自己这边，而是平台状态，先打开 OpenAI Status。按 2026 年 3 月 22 日 的公开状态，系统整体是正常的。也就是说，今天你遇到的局部失败更应该先按本地配置去查，而不是默认成全局事故。

如果你的主问题还停留在“为什么明明 verified 了还是用不了”，下一步更值得看的是中文的 OpenAI 图像 API 认证错误排查。

上线前的检查清单

当第一条请求成功以后，真正正确的下一步不是立刻把工程抽象得更复杂，而是把后面最容易反复踩坑的几件事固定下来。

建议按这个顺序做：

1. 先固定路线。 如果功能主体是直接出图或编辑，就继续用 Images API；只有当图片只是更大流程的一步时，才迁到 Responses API。
2. 再固定模型。 默认从 GPT Image 1.5 开始；只有预算明显更重要时，再去测 gpt-image-1-mini。
3. 固定一套默认输出参数。 先定一个默认尺寸、默认质量和默认输出格式，再慢慢把选项暴露给用户。
4. 提前记录排错上下文。 把当前组织、模型 ID、使用的 endpoint、失败类型记录下来，这比事后翻日志更省时间。
5. 把“教程成功”与“成本可控”拆开看。 请求能跑通，不代表规模化后账单一定合理。

这也是为什么一个好教程应该自然交给读者下一步，而不是假装自己已经解决了所有问题。当前最有价值的后续阅读通常是：

• OpenAI 图像生成 API 定价
• OpenAI 图像 API 认证错误排查
• 英文版 How to get an OpenAI API key
• 英文版 OpenAI API key requirements

归根结底，当前 OpenAI Image API 教程真正要解决的，不是代码块本身，而是先选对 API 路线、用对当前模型、把访问关卡清掉，然后再去调那些真的会改变质量、延迟和成本的参数。 顺序一旦对了，这个话题会比搜索页看起来简单很多。

常见问题

应该先学 Images API 还是 Responses API？

如果你的任务是直接生成图片或编辑图片，先学 Images API。只有当图片生成只是更大助手工作流中的一个工具时，才更适合从 Responses API 开始。

新教程默认应该用哪个模型？

对大多数人来说，gpt-image-1.5 是最稳的当前默认值。只有当预算是第一约束时，才优先测试 gpt-image-1-mini。

为什么示例代码看起来没错，但还是调不通？

最常见的原因不是代码，而是 usage tier、组织验证、当前组织上下文 或 旧 API key。先排这些，再怀疑 SDK。

什么时候该用 chatgpt-image-latest，而不是 gpt-image-1.5？

只有当你明确想对齐 ChatGPT 当前图像快照时，才优先考虑 chatgpt-image-latest。如果你写的是长期可维护的生产教程，gpt-image-1.5 通常更适合。