GPT-IMAGE-2 API 保姆级教程：创建图像接口的调用步骤详解

如果你正在接入图像生成能力，那么 gpt-image-2 的创建图像接口是一个比较清晰、直接的起点。本文基于接口文档内容，整理出一篇更适合阅读与检索的教程说明，帮助你快速了解接口用途、调用流程、参数含义以及常见错误处理方式。

一、什么是 GPT-IMAGE-2 创建图像接口

gpt-image-2 用于根据文本提示词生成全新图像，请求方式为 POST，接口路径为：

它的核心用途是：输入一段描述性文本，由模型生成对应图像结果。

二、GPT-IMAGE-2 特性

• 支持高分辨率输出，可到 4K

• 支持流式传输，可边生成边返回部分图像结果

• 返回图像数据时可使用 base64 编码

• 不支持透明背景

同时也有两点需要提前注意：

• 当提示词较复杂时，生成过程可能需要 约 2 分钟

• 超过 2560×1440（约 368 万像素）的输出能力属于实验性范围，使用时建议做好兼容处理

三、调用 GPT-IMAGE-2 创建图像接口的基本步骤

第 1 步：准备请求地址与鉴权信息

发起请求前，需要准备以下内容：

• 接口基础地址（Base URL）

• API Key

• 请求方式：POST

• 接口路径：/v1/images/generations

请求头通常包含：

其中：

• Authorization 用于身份校验

• Content-Type 固定为 application/json

第 2 步：设置模型名称

请求体中需要传入 model 参数，并固定填写为：

这是必填项，用于当前调用的图像模型。

第 3 步：编写提示词

prompt prompt 是图像生成请求中关键的字段，用于描述你希望模型生成什么内容。

示例：

文档说明中，prompt 至高可支持约 32000 字符，因此它不仅适合简单描述，也适合较复杂的场景设定。

第 4 步：设置生成数量 n

参数 n 表示一次请求生成的图像数量。

类型：integer

可选范围：1 ~ 10

默认值：1

示例：

如果只是测试接口或做常规调用，通常保留默认值即可。

第 5 步：设置图像尺寸 size

size 用于控制输出分辨率。文档中给出了多个可选值：

• 1024x1024：方形，速度通常更快

• 1536x1024：横向

• 1024x1536：纵向

• 2048x2048：2K 方形

• 2048x1152：2K 横向

• 3840x2160：4K 横向

• 2160x3840：4K 纵向

• auto：由模型自动选择适配尺寸

还需要注意以下限制：

• 边长不超过 3840px

• 宽高都需要是 16px 的倍数

• 长宽比不能超过 3:1

• 总像素数需在 655,360 到 8,294,400 之间

如果不确定该如何选，建议先用：

第 6 步：设置图像质量 quality

quality 用于控制图像渲染质量，可选值包括：

• low：速度更快，适合草图、缩略图和快速迭代

• medium：中等质量

• high：高质量，适合成果输出

• auto：默认，由模型自动选择

示例：

如果你的目标是先验证生成逻辑，可以先用 low 或 auto；如果更重视高质量画质，可以选择 high。

第 7 步：设置输出格式 output_format

接口支持以下输出文件格式：

• png：默认格式，适合保留更完整的图像信息

• jpeg：体积通常更小，传输更轻量

• webp

示例：

第 8 步：按需设置压缩率 output_compression

如果输出格式为 jpeg 或 webp，还可以通过 output_compression 设置压缩级别：

• 类型：integer

• 范围：0 ~ 100

例如：

需要注意：

• 该参数仅对 jpeg 和 webp 有效

• 对 png 不生效

第 9 步：设置背景 background background

用于背景控制，可选值包括：

• opaque：不透明背景

• auto：默认，由模型自动选择

示例：

特别说明：gpt-image-2 不支持 transparent（透明背景），因此不要传入透明背景相关值。

第 10 步：设置内容审核等级 moderation

moderation 用于内容审核控制，可选值包括：

• auto：默认，标准过滤策略

• low：较宽松的过滤策略

示例：

通常保持默认值即可。

第 11 步：按需启用流式传输 stream

如果你希望在生成过程中提前接收部分图像结果，可以启用流式输出：

当 stream 为 true 时，可以结合 partial_images 使用。

第 12 步：设置 partial_images 返回中间结果数量

partial_images 表示流式传输过程中返回的部分图像数量（0-3）：

• 0：仅返回终态图像

• 1 ~ 3：返回特定数量的部分图像（中间进度图）

示例：

如果图像综合来看生成速度较快，实际收到的中间图数量可能少于请求值，这是正常现象。

四、请求示例

你可以通过任意支持 HTTP 的方式调用该接口。下面以通用请求结构示意：

请求体为 JSON。

五、成功响应说明

当请求成功后，接口会返回 200 状态码，响应体中通常包含：

• created：创建时间，Unix 时间戳

• data：图像结果数组

返回示意：

其中：

• b64_json 表示 Base64 编码后的图像数据

• 部分场景下也可能包含图像 URL 或提示词修订信息等字段

六、常见错误与处理方式

1）400 参数错误

当请求参数不合法时，接口会返回 400。

例如尺寸参数不符合要求，可能返回类似信息：

常见原因包括：

• size 不在允许范围内

• 宽高不是 16 的倍数

• 长宽比超限

• 像素总量不符合约束

2）401 API Key 无效或缺失

如果未传入 API Key，或 Key 填写错误，通常会返回 401：

排查方式：

• 检查 Authorization 请求头是否存在

• 确认格式是否为 Bearer 你的API_KEY

• 确认 Key 是否可用、是否过期

3）429 请求频率超限

如果请求过于频繁，可能会收到 429：

处理建议：

• 控制请求频率

• 增加重试间隔

• 避免短时间内高并发重复提交

七、GPT-IMAGE-2 的几个实用建议

为了让接口调用更稳定，实际使用中可以注意以下几点：

1. 先用小尺寸调试 在开发初期，建议优先使用 1024x1024 或 auto，这样更容易快速验证参数和返回结构。

2. 复杂提示词要预留时间 当提示词描述层次较多、风格要求较细时，生成耗时会更长，接口侧需要预留更充足的超时时间。

3. 高分辨率输出适合终局结果 如需 2K 或 4K 输出，建议在功能验证完成后再使用，以减少调试支出。

4. 流式传输适合需要进度反馈的场景 如果前端需要展示“生成中”的视觉过程，可以启用 stream 和 partial_images。

5. 不要传透明背景 文档已经明确说明该模型不支持透明背景，因此背景参数应使用 auto 或 opaque。

八、总结

总的来说，gpt-image-2 的创建图像接口上手门槛并不高，只要理清 model、prompt、size、quality 等核心参数，并结合业务场景处理好超时、限流和参数校验，就可以比较顺利地完成图像生成能力接入。对于初次使用的开发者，建议先从小尺寸、单张生成和非流式调用开始验证，再逐步扩展到高分辨率、多图生成和流式返回等能力。这样不仅更利于排查问题，也能更快搭建出稳定可用的图像生成流程。