OpenAI 编辑图像接口

创建图像编辑

post /images/edits

根据一张或多张原图和提示词创建编辑后或扩展后的图像。此接口支持 GPT Image 模型。

请求体参数

内容类型为 application/json。

images: array of object { file_id, image_url }

待编辑的输入图像引用。 GPT Image 模型最多可提供 16 张图像。

minItems: 1, maxItems: 16

file_id: optional string

用作输入的已上传图像的 Files API ID。

image_url: optional string

完整 URL 或 Base64 编码的 data URL。

maxLength: 20971520, format: uri

prompt: string

对所需图像编辑效果的文本描述。

minLength: 1, maxLength: 32000

background: optional "transparent" or "opaque" or "auto" or null (default: "auto")

设置生成图像的背景。gpt-image-2.5-sunburst 和 gpt-image-2.5-flare（含其 2026-09-08 快照）支持 opaque 和 transparent。支持此功能的 GPT Image 模型可生成透明背景。gpt-image-2 和 gpt-image-2-2026-04-21 的透明背景功能处于预览阶段。使用 transparent 时，输出格式须设为 png 或 webp。

"transparent"

"opaque"

"auto"

complexity: optional "low" or "medium" or "high" or null

用于规划图像的计算投入，独立于渲染质量。省略时使用图像模型配置的默认值。对于 SVG 输出，此项控制参考图像，独立于 SVG 编写模型的推理。

"low"

"medium"

"high"

frame_count: optional integer or null

GIF 输出的帧数，接受 2–16 的整数，省略时默认为 9。仅在 output_format=gif 时支持。请求尺寸须符合所选模型的 GIF 尺寸限制。GIF 输出不支持流式传输、部分图像、蒙版或自定义输出压缩，并要求具有所选模型的 GIF 预览权限。

minimum: 2, maximum: 16

frame_duration_ms: optional integer or null

GIF 每帧的请求延迟，单位为毫秒，省略时默认为 200。GIF 输出会将延迟取整到最接近的 10 毫秒，每帧编码延迟上限为 655,350 毫秒。仅在 output_format=gif 时支持。

minimum: 20

input_fidelity: optional "high" or "low" or null

控制模型为匹配输入图像风格和特征（尤其是面部特征）投入的程度。gpt-image-1.5 支持 high 和 low，gpt-image-1-mini 仅支持 low。使用 gpt-image-2 时应省略此参数。支持该参数的模型默认为 low。

"high"

"low"

markup: optional object { file_id, image_url }

叠加在第一张图像上的透明 PNG，可通过文件 ID、HTTPS URL 或 Base64 data URL 引用。其尺寸须与应用方向信息后的原图相同，且包含透明像素。GPT Image 2.5 支持。不能与 mask 同时使用。

file_id: optional string

用作输入的已上传图像的 Files API ID。

image_url: optional string

完整 URL 或 Base64 编码的 data URL。

maxLength: 20971520, format: uri

mask: optional object { file_id, image_url }

通过 URL 或已上传文件的 ID 引用输入图像。 image_url 和 file_id 必须且只能提供其中一项。

file_id: optional string

用作输入的已上传图像的 Files API ID。

image_url: optional string

完整 URL 或 Base64 编码的 data URL。

maxLength: 20971520, format: uri

model: optional string or "gpt-image-1.5" or "gpt-image-2" or "gpt-image-2-2026-04-21" or 9 more or null (default: "gpt-image-2.5-sunburst")

用于图像编辑的 GPT Image 模型，包括 gpt-image-2、其日期快照 gpt-image-2-2026-04-21、gpt-image-2.5-sunburst、 gpt-image-2.5-sunburst-2026-09-08、gpt-image-2.5-flare、 gpt-image-2.5-flare-2026-09-08、gpt-image-2.6-sunburst 和 gpt-image-2.6-flare。默认为 gpt-image-2.5-sunburst。

gpt-image-1 已于 2026 年 10 月 23 日停用，请使用 gpt-image-2.5-sunburst 或 gpt-image-2.5-flare。

string

"gpt-image-1.5" or "gpt-image-2" or "gpt-image-2-2026-04-21" or 9 more

gpt-image-1 已于 2026 年 10 月 23 日停用，请使用 gpt-image-2.5-sunburst 或 gpt-image-2.5-flare。

"gpt-image-1.5"

"gpt-image-2"

"gpt-image-2-2026-04-21"

"gpt-image-2.5-sunburst"

"gpt-image-2.5-sunburst-2026-09-08"

"gpt-image-2.5-flare"

"gpt-image-2.5-flare-2026-09-08"

"gpt-image-2.6-sunburst"

"gpt-image-2.6-flare"

"gpt-image-1"

"gpt-image-1-mini"

"chatgpt-image-latest"

moderation: optional "low" or "auto" or null (default: "auto")

GPT Image 模型的内容审核级别。

"low"

"auto"

n: optional integer or null (default: 1)

要生成的编辑后图像数量。

minimum: 1, maximum: 10

output_compression: optional integer or null

jpeg 或 webp 输出的压缩级别。

minimum: 0, maximum: 100

output_format: optional "png" or "webp" or "jpeg" or 2 more or null (default: "png")

输出图像格式，GPT Image 模型支持。SVG 输出要求使用支持的图像模型，并具备项目访问权限。

"png"

"webp"

"jpeg"

"gif"

"svg"

partial_images: optional integer or null (default: 0)

要生成的部分图像数量。此参数用于返回部分图像的流式响应，值必须为 0–3。设为 0 时，响应通过单个流式事件发送一张图像。

如果完整图像生成得更快，最终图像可能会在全部请求的部分图像生成之前发出。

minimum: 0, maximum: 3

quality: optional "low" or "medium" or "high" or 3 more or null (default: "auto")

GPT Image 模型的输出质量。GPT Image 模型支持 low、medium 和 high。gpt-image-2.5-sunburst 和 gpt-image-2.5-flare（包括其 2026-09-08 快照）还支持 xhigh 和 max。默认为 auto。

"low"

"medium"

"high"

"xhigh"

"max"

"auto"

safety_identifier: optional string or null

组织内终端用户的稳定标识，用于安全监测和滥用检测。可对用户名或电子邮箱做哈希，避免发送身份信息。非空值优先于已弃用的 user 参数。若省略、为 null 或为空，API 会使用可用的 user 值。参阅安全标识说明。

maxLength: 128

size: optional string or "auto" or "1024x1024" or "1536x1024" or "1024x1536" or null (default: "auto")

生成图像的尺寸。gpt-image-2、gpt-image-2-2026-04-21、gpt-image-2.5-sunburst、gpt-image-2.5-sunburst-2026-09-08、gpt-image-2.5-flare 和 gpt-image-2.5-flare-2026-09-08 支持以 WIDTHxHEIGHT 字符串指定任意分辨率，例如 1536x864。宽和高均须能被 16 整除，宽高比须在 1:3 至 3:1 之间。高于 2560x1440 的分辨率属于实验功能，支持的最高分辨率为 3840x2160。尺寸还须符合模型当前的像素数与边长限制。GPT Image 模型支持标准尺寸 1024x1024、1536x1024 和 1024x1536；允许自动尺寸的模型支持 auto。

string

"auto" or "1024x1024" or "1536x1024" or "1024x1536"

"auto"

"1024x1024"

"1536x1024"

"1024x1536"

stream: optional boolean or null (default: false)

以事件流方式传输部分图像结果。

svg: optional object { model, reasoning } or null

为 output_format=svg 选择 SVG 编写模型和推理强度。已启用 SVG 模型选择时须提供 svg.model，否则省略此对象。SVG 输出要求 n=1，并且不能使用流式传输、部分图像或输出压缩。

model: optional string

minLength: 1

reasoning: optional object { effort } or null

SVG 编写的推理强度。省略时，Images 和 Responses 均使用编写模型的默认值。

effort: optional "none" or "minimal" or "low" or 4 more

控制模型为此次请求投入的推理强度。

"none"

"minimal"

"low"

"medium"

"high"

"xhigh"

"max"

user: optional string

此参数已弃用，请改用 safety_identifier。为保持向后兼容仍接受此参数，且在 safety_identifier 省略、为 null 或为空时使用。参阅安全标识说明。

返回值

ImagesResponse object { created, background, data, 6 more }

图像生成接口的响应。

created: integer

图像创建时间，采用 Unix 时间戳，单位为秒。

format: unixtime

background: optional "transparent" or "opaque"

生成图像使用的背景参数，值为 transparent 或 opaque。

"transparent"

"opaque"

data: optional array of Image

生成的图像列表。

b64_json: optional string

包含 Base64 编码图像的 JSON 字段。GPT Image 模型默认返回；支持 response_format 的模型在设为 b64_json 时返回。

revised_prompt: optional string

支持提示词改写的模型用于生成图像的改写后提示词。GPT Image 模型不返回此字段。

url: optional string

支持该参数的模型在 response_format 设为 url 时返回的生成图像 URL。GPT Image 模型不支持此返回方式。

format: uri

output_format: optional "png" or "webp" or "jpeg" or 2 more

生成或编辑后图像的输出格式。

"png"

"webp"

"jpeg"

"gif"

"svg"

quality: optional "low" or "medium" or "high" or 2 more

生成图像的质量，可选 low、medium、high、xhigh 或 max。

"low"

"medium"

"high"

"xhigh"

"max"

safety_identifier: optional string or null

用于安全监测和滥用检测的实际安全标识。优先使用请求中非空的 safety_identifier；如果省略、为 null 或为空，则使用已弃用的 user 值。

size: optional string or "1024x1024" or "1024x1536" or "1536x1024"

图像尺寸，采用 WIDTHxHEIGHT 字符串形式，例如 1536x864。

string

"1024x1024" or "1024x1536" or "1536x1024"

图像尺寸，采用 WIDTHxHEIGHT 字符串形式，例如 1536x864。

"1024x1024"

"1024x1536"

"1536x1024"

svg_usage: optional object { input_tokens, model, output_tokens, 2 more }

SVG 编写的词元用量，与图像渲染用量分别记录。

input_tokens: integer

model: string

output_tokens: integer

reasoning_tokens: integer

total_tokens: integer

usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }

GPT Image 模型生成图像的词元用量。

input_tokens: integer

输入提示词中的图像与文本词元数量。

input_tokens_details: object { image_tokens, text_tokens }

图像生成的输入词元明细。

image_tokens: integer

输入提示词中的图像词元数量。

text_tokens: integer

输入提示词中的文本词元数量。

output_tokens: integer

模型生成的输出词元数量。

total_tokens: integer

图像生成使用的图像和文本词元总数。

output_tokens_details: optional object { image_tokens, text_tokens }

图像生成的输出词元明细。

image_tokens: integer

模型生成的图像输出词元数量。

text_tokens: integer

模型生成的文本输出词元数量。

示例

## 设置 OPENAI_API_KEY，并根据请求替换图像地址、文件 ID 和提示词。
curl https://api.openai.com/v1/images/edits \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
          "images": [
            {
              "image_url": "https://example.com/source-image.png"
            }
          ],
          "prompt": "为这张图像添加水彩效果",
          "model": "gpt-image-1.5",
          "quality": "high",
          "size": "1024x1024"
        }'

200 响应示例

{
  "created": 0,
  "background": "transparent",
  "data": [
    {
      "b64_json": "b64_json",
      "revised_prompt": "revised_prompt",
      "url": "https://example.com"
    }
  ],
  "output_format": "png",
  "quality": "low",
  "safety_identifier": "safety_identifier",
  "size": "1024x1024",
  "svg_usage": {
    "input_tokens": 0,
    "model": "model",
    "output_tokens": 0,
    "reasoning_tokens": 0,
    "total_tokens": 0
  },
  "usage": {
    "input_tokens": 0,
    "input_tokens_details": {
      "image_tokens": 0,
      "text_tokens": 0
    },
    "output_tokens": 0,
    "total_tokens": 0,
    "output_tokens_details": {
      "image_tokens": 0,
      "text_tokens": 0
    }
  }
}

编辑图像示例

## 设置 OPENAI_API_KEY，并根据请求替换图像地址、文件 ID 和提示词。
curl -s -D >(grep -i x-request-id >&2) \
  -o >(jq -r '.data[0].b64_json' | base64 --decode > gift-basket.png) \
  -X POST "https://api.openai.com/v1/images/edits" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F "model=gpt-image-1.5" \
  -F "image[]=@body-lotion.png" \
  -F "image[]=@bath-bomb.png" \
  -F "image[]=@incense-kit.png" \
  -F "image[]=@soap.png" \
  -F 'prompt=用这四件物品组成一个精美的礼品篮'

使用图像 URL 的 JSON 请求

## 设置 OPENAI_API_KEY，并根据请求替换图像地址、文件 ID 和提示词。
curl https://api.openai.com/v1/images/edits \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
          "images": [
            {
              "image_url": "https://example.com/source-image.png"
            }
          ],
          "prompt": "为这张图像添加水彩效果",
          "model": "gpt-image-1.5",
          "quality": "high",
          "size": "1024x1024"
        }'

使用已上传文件 ID 的 JSON 请求

## 设置 OPENAI_API_KEY，并根据请求替换图像地址、文件 ID 和提示词。
curl https://api.openai.com/v1/images/edits \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
          "images": [
            {
              "file_id": "file-abc123"
            }
          ],
          "prompt": "将背景替换为雪山景色",
          "mask": {
            "file_id": "file-mask123"
          },
          "model": "gpt-image-1.5",
          "output_compression": 100,
          "output_format": "png"
        }'

流式响应示例

## 设置 OPENAI_API_KEY，并根据请求替换图像地址、文件 ID 和提示词。
curl -s -N -X POST "https://api.openai.com/v1/images/edits" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F "model=gpt-image-1.5" \
  -F "image[]=@body-lotion.png" \
  -F "image[]=@bath-bomb.png" \
  -F "image[]=@incense-kit.png" \
  -F "image[]=@soap.png" \
  -F 'prompt=用这四件物品组成一个精美的礼品篮' \
  -F "stream=true"

响应示例

event: image_edit.partial_image
data: {"type":"image_edit.partial_image","b64_json":"...","partial_image_index":0}

event: image_edit.completed
data: {"type":"image_edit.completed","b64_json":"...","usage":{"total_tokens":100,"input_tokens":50,"output_tokens":50,"input_tokens_details":{"text_tokens":10,"image_tokens":40}}}