GPT-Image 2 使用教程

GPT-Image 2 提供 OpenAI Images 兼容的图片生成与编辑能力：文生图、单图编辑、多图融合和蒙版局部重绘。模型原生支持中文提示词。

本目录中的接口使用 NiceRouter API 地址和 NiceRouter API Key；不要把第三方服务的控制台地址、组织标识或 API Key 写入业务代码、前端或文档示例。

1. 快速开始

模型：gpt-image-2（固定）

文生图：POST /v1/images/generations，请求体为 JSON

编辑 / 多图融合 / 蒙版重绘：POST /v1/images/edits，本地文件用 multipart/form-data

鉴权：Authorization: Bearer <NiceRouter API Key>

Base URL：https://ee.nicerouter.com

在 Apifox 中，选择 用户版环境，并将请求头的 {{YOUR_API_KEY}} 替换为自己的 NiceRouter API Key。API Key 只应保存在服务端环境变量或 Apifox 本地环境变量中，不能提交到代码仓库。

2. 文生图

调用 GPT-Image 2 文生图 接口，传入 model 和 prompt。每次请求只生成一张图片，n 对文生图不生效。

2.1 请求参数

参数	必填	说明
`model`	是	固定为 `gpt-image-2`。
`prompt`	是	生成指令，支持中文。应描述主体、场景、构图、材质、光线、风格、需要显示的文字。
`size`	否	可传显式像素尺寸（例如 `1024x1024`、`1024x1536`），或 `1K` / `2K` / `4K` 分辨率档位。
`aspectRatio`	否	宽高比，例如 `1:1`、`3:4`、`16:9`。使用分辨率档位时建议同时设置。
`quality`	否	`auto`、`low`、`medium`、`high`；不传默认为 `auto`。
`background`	否	`auto`、`opaque`、`transparent`。真实透明背景必须搭配 `quality=medium` 或 `high`。

2.2 提示词建议

提示词应明确：

主体与数量：例如“一个白色陶瓷杯”，不要只写“杯子”。

构图与画幅：例如“正方形居中构图”“竖版海报，人物居中”。

视觉属性：材质、光线、颜色、镜头或艺术风格。

必须保留或避免的内容：例如“白色纯净背景，无水印，无额外文字”。

画面文字：直接写出需显示的精确中文，并说明位置、字重和层级。

{
  "model": "gpt-image-2",
  "prompt": "竖版 3:4 电商海报：一双白色运动鞋置于浅蓝色几何展台，柔和侧光，高端棚拍质感。顶部显示清晰中文标题“轻盈出发”，底部小字“2026 春季系列”。无水印，无多余文字。",
  "size": "2K",
  "aspectRatio": "3:4",
  "quality": "high"
}

3. 图片编辑

调用 GPT-Image 2 图片编辑与多图融合 接口。根据图片来源选择提交形式：

本地文件：使用 multipart/form-data。

已托管的公开 HTTPS 图片、Data URL 或原始 Base64：可以使用 JSON 请求体。

公网 URL 必须能被服务端访问；私网、回环地址和云元数据地址不能使用。

3.1 单图编辑

上传一张本地文件，字段名为 image：

3.2 多图融合

最多上传 16 张 PNG、JPEG 或 WebP 参考图片。重复提交 image[] 字段；上传顺序就是提示词里的“图片 1”“图片 2”“图片 3”。

x-input-image-compress: true 是可选请求头，仅压缩大于 200KB 的上传参考图，以减少传输和存储开销；它不压缩输出图片。

3.3 JSON 形式的 URL 图片编辑

对于已在自己 CDN 托管的公开图片，可用 JSON：

JSON 多图字段优先使用 images；兼容字段 input_images 也可使用。

4. 蒙版局部重绘

蒙版只支持编辑接口的 multipart/form-data 请求。它适合更换衣服、替换背景中的局部物体、扩展场景等。

4.1 蒙版硬性要求

必须为 RGBA PNG，不能是没有 Alpha 通道的 RGB、灰度或调色板 PNG。

尺寸必须与第一张源图逐像素一致，差 1 个像素也会失败。

透明区域会重绘；不透明区域会保留。这与一些黑白蒙版工作流的直觉相反，提交前应检查 Alpha 通道。

蒙版应用于第一张 image / image[]。

单个蒙版建议小于 4MB。

4.2 蒙版提示词原则

GPT-Image 2 是提示词引导的整图再生成，不是严格的像素复制。即使不透明区域被要求保留，阴影、反射、光线和边缘过渡也可能轻微改变。

因此提示词必须：

描述完整的目标画面，而不是只写“把这里改成窗户”；

明确“只修改透明区域”；

明确人物面部、姿势、主体颜色、背景等必须保持不变的要素。

若业务要求未修改区域字节级完全一致，应在服务端收到生成结果后，通过原图与蒙版进行二次合成，并对边缘做羽化处理。

5. 尺寸、质量与背景

5.1 尺寸选择

可直接传像素尺寸，或传档位加宽高比：

{ "size": "1024x1536" }

{ "size": "2K", "aspectRatio": "3:4" }

编辑接口的关键限制：当 size 为 1K、2K 或 4K 时，必须同时传 aspectRatio，或者改用显式像素尺寸。只传档位会导致实际渲染降为自动尺寸，响应仍可能显示请求的档位并按该档位计费。

5.2 质量与透明背景

目标	推荐参数
快速草图	`quality: low`
常规出图	`quality: auto`
商品主图、海报、文字细节	`quality: high`
需要透明 PNG 背景	`background: transparent` 且 `quality: medium` 或 `high`

使用 background=transparent 与 quality=low 时，服务可能返回 HTTP 200 但输出实际是不透明背景。必须解码 PNG 并检查 Alpha 通道，不能仅依赖响应状态码。

6. 编辑专属参数

参数	说明
`image`	单图编辑时上传一个本地文件。
`image[]`	多图融合时重复使用，最多 16 张。
`mask`	可选 RGBA PNG；透明处重绘，仅作用于第一张源图。
`output_format`	仅编辑接口有效：`png`、`jpeg`、`webp`；默认 `png`。
`n`	仅编辑接口有效，只有 `n > 1` 时才请求多张输出。
`quality` / `background` / `size` / `aspectRatio`	语义与文生图相同。

7. 响应与结果保存

接口返回完整 JSON，不提供流式局部图片。data[] 中每个元素可能包含：

url：临时访问地址，应立即下载并转存至自己的对象存储。

b64_json：不含 Data URL 前缀的原始 Base64。浏览器显示前要拼接 data:image/png;base64,。

usage：可能包含 input_tokens、output_tokens、total_tokens、generated_images。

{
  "created": 1767321600,
  "data": [
    {
      "url": "https://temporary-image-url.example/image.png"
    }
  ],
  "usage": {
    "output_tokens": 4096,
    "total_tokens": 4096,
    "generated_images": 1
  }
}

Node.js 保存 Base64 示例：

8. 常见问题排查

请求成功但图片尺寸不对

编辑时只传了 1K / 2K / 4K，没有 aspectRatio。改为同时传例如 { "size": "2K", "aspectRatio": "3:4" }，或改传显式像素尺寸。并下载结果检查实际像素尺寸。

蒙版没有生效或报图片格式错误

确认蒙版是带 Alpha 的 RGBA PNG，且宽高与第一张源图严格相等。确认要修改的区域是透明的，而不是黑色。

透明背景没有输出 Alpha

确认传入 background=transparent 和 quality=medium 或 high；再下载 PNG 检查 Alpha 通道。

多图融合中引用错了图片

多图使用的不是单个 image，而是重复的 image[]。提示词中的“图片 1 / 图片 2 / 图片 3”严格对应上传顺序。

返回 URL 后图片无法长期访问

返回 URL 是临时链接。服务端拿到后应立即下载、校验文件类型和大小，并写入自己的对象存储；不要让前端长期依赖该链接。

系统繁忙或生成失败

对于服务端返回的繁忙类错误，记录请求 ID 与错误信息，向调用方返回可重试错误并做有限次数的退避重试；不要无限重试或延长单次请求超时。

9. 上线检查清单

API Key 仅在服务端保管，不写入浏览器、移动端或 Git。

文生图请求包含 model 和清晰的 prompt。

编辑请求使用 1K / 2K / 4K 时包含 aspectRatio。

多图请求使用重复的 image[]，并在提示词中按上传顺序引用。

蒙版为同尺寸 RGBA PNG，透明处才是重绘区域。

透明背景使用 quality=medium 或 high，并检查生成 PNG 的 Alpha。

将临时 URL 转存到自己的对象存储。

记录实际图像尺寸、响应耗时、状态码和请求错误，便于排查。

10. 推荐尺寸对照表

以下尺寸可直接作为 size 传入。显式尺寸同时确定画幅与分辨率；模型实际返回的像素可能有轻微差异，交付时仍应读取生成文件的实际宽高。

宽高比	1K	2K	4K
`1:1`	`1280x1280`	`2048x2048`	`2880x2880`
`16:9`	`1280x720`	`2048x1152`	`3840x2160`
`9:16`	`720x1280`	`1152x2048`	`2160x3840`
`4:3`	`1280x960`	`2048x1536`	`3312x2480`
`3:4`	`960x1280`	`1536x2048`	`2480x3312`
`3:2`	`1280x848`	`2048x1360`	`3520x2336`
`2:3`	`848x1280`	`1360x2048`	`2336x3520`
`5:4`	`1280x1024`	`2048x1632`	`3216x2560`
`4:5`	`1024x1280`	`1632x2048`	`2560x3216`
`21:9`	`1280x544`	`2048x864`	`3840x1632`

尺寸字符串里的分隔符必须为半角小写 x，例如 1728x2304；不要使用大写 X 或乘号 ×。

11. OpenAI Images 兼容性

接口形状与 OpenAI Images API 兼容，但并非每个 OpenAI 参数都在所有场景下有效。未支持的参数可能被忽略，调用方不得据此假设功能已经生效。

参数	文生图	编辑	规则
`model`	必填	必填	固定 `gpt-image-2`。
`prompt`	必填	必填	使用完整、可验证的描述。
`size`	支持	支持	编辑传档位时必须配合 `aspectRatio`。
`quality`	支持	支持	`auto` / `low` / `medium` / `high`。
`background`	支持	支持	透明背景需 `medium` 或 `high`。
`aspectRatio` / `aspect_ratio`	支持	支持	网关扩展；编辑使用分辨率档位时为必填。
`image` / `images`	不适用	支持	本地文件用 multipart；URL、Data URL、Base64 可用 JSON。
`input_images`	不适用	兼容	新接入优先用 `image` / `images`。
`mask`	不适用	支持	仅 multipart，且为同尺寸 RGBA PNG。
`output_format`	不支持	支持	`png` / `jpeg` / `webp`。
`n`	不支持	`n > 1` 时支持	文生图始终只返回一张。
`output_compression`	不支持	不支持	不会压缩输出；不要与 `x-input-image-compress` 混淆。
`stream` / `partial_images`	不支持	不支持	始终等待并返回完整 JSON 响应。

x-input-image-compress 只优化编辑请求中上传的输入参考图，并不改变 output_format，也不压缩生成的结果文件。

12. 生产接入、计费和超时

12.1 超时与重试

图片生成时间取决于画幅、质量和输入图片数量。客户端读取超时建议至少设置为 600 秒；不要把高质量、多图或 4K 请求放在默认 30 秒 HTTP 超时内。

参考延迟范围：

场景	常见耗时
`quality=low`	约 10–40 秒
`quality=medium`	约 30–90 秒
`quality=high`、复杂 2K / 4K 编辑	约 3–5 分钟
多图融合	通常比单图编辑更久；按最复杂场景设置超时。

仅对连接中断、超时、临时 5xx 等可判定的瞬时失败做有限次数指数退避重试。服务端返回“系统繁忙”或类似处理错误时，不要在同一请求链中无限重试；返回可重试错误并让用户稍后再试。

12.2 计费与可观测性

图片通常按最终规格和质量档计费；实际模型、可用规格和组织价格应以 NiceRouter 控制台当前展示为准。不要根据 usage 中是否存在 token 字段推导价格。

生产环境至少记录：请求时间、模型、显式尺寸或档位+宽高比、质量档、输入图数量、返回的实际像素、状态码、耗时与错误码。日志不得记录 API Key、完整 Base64 图片或含签名的临时 URL 查询参数。

12.3 结果存储与内容安全

返回的 URL 可能过期。后端应立即下载并校验 Content-Type、图像解码有效性、文件大小和实际尺寸，再写入自有对象存储。外部图片 URL 仅接受可信的公开 HTTPS 地址；不要让业务系统把内网、回环、元数据或用户未授权的资源 URL 传给上游。

GPT-Image 2 使用教程

1. 快速开始#

2. 文生图#

2.1 请求参数#

2.2 提示词建议#

3. 图片编辑#

3.1 单图编辑#

3.2 多图融合#

3.3 JSON 形式的 URL 图片编辑#

4. 蒙版局部重绘#

4.1 蒙版硬性要求#

4.2 蒙版提示词原则#

5. 尺寸、质量与背景#

5.1 尺寸选择#

5.2 质量与透明背景#

6. 编辑专属参数#

7. 响应与结果保存#

8. 常见问题排查#

请求成功但图片尺寸不对#

蒙版没有生效或报图片格式错误#

透明背景没有输出 Alpha#

多图融合中引用错了图片#

返回 URL 后图片无法长期访问#

系统繁忙或生成失败#

9. 上线检查清单#

10. 推荐尺寸对照表#

11. OpenAI Images 兼容性#

12. 生产接入、计费和超时#

12.1 超时与重试#

12.2 计费与可观测性#

12.3 结果存储与内容安全#