OpenAI Images Edits API 申请及使用

OpenAI 图片编辑服务，可以传入图片和指令，输出修改之后的图片。GPT Image 系列模型最多可同时传入 16 张参考图。目前接口同时支持 gpt-image-1、最新的 gpt-image-2，以及通过同一接口接入的 nano-banana / nano-banana-2-lite / nano-banana-2 / nano-banana-pro 系列模型。本文档主要介绍 OpenAI Images Edits API 操作的使用流程，利用它我们可以轻松使用官方 OpenAI 图像编辑功能。

申请流程

要使用 OpenAI Images Edits API，首先到 Ace Data Cloud 控制台获取您的 API Token，留作备用。

如果你尚未登录或注册，会自动跳转到登录页面邀请你注册和登录，完成后会自动返回当前页面。 一个 API Token 即可调用平台所有服务，无需为每个服务单独申请。 首次申请会赠送免费额度，可免费体验；额度不足时可在控制台充值通用余额。

📘 完整文档：OpenAI Images Edits API →

GPT-Image-2 模型

gpt-image-2 在图像编辑场景下相比 gpt-image-1 有非常明显的提升：

结构保持更稳定：换皮肤、换配色、换背景时几乎不会破坏原图的版式与构图。
文字保留更准确：信息图、海报、菜单等含文字的图片在编辑后文字仍然清晰可读。
支持 URL 直传：除了传统的 multipart/form-data 文件上传，gpt-image-2 还额外支持以 JSON 方式传入图片 URL，无需先把图片下载到本地，非常适合服务端流水线接入。
支持 base64 直传：和官方一致，image 字段也可以直接传 base64（data:image/png;base64,... 或裸 base64），本地图片无需先上传到图床即可编辑。
支持高分辨率重绘：可以传入一张 1K 原图，通过 size 参数请求 2K / 4K 输出，模型会在编辑过程中同时完成放大。

线路变体（`:official` / `:reverse`）

gpt-image-2 默认走标准线路。通过模型名后缀可以显式选择线路：

gpt-image-2:official：官方通道，稳定合规。支持真实 2K / 4K 高分辨率，按每张图片计费，单价为默认 gpt-image-2 的 2 倍。线路不可用时直接返回错误，不会自动降级。
gpt-image-2:reverse：与默认 gpt-image-2 完全等价，性价比更高，价格不变。

支持的 `size` 取值

编辑接口对 size 的格式校验与生成接口一致——gpt-image-2 只需要 size 为 auto、空，或者符合 WIDTHxHEIGHT 格式，任何其他形态会返回 400。所有尺寸（1K / 2K / 4K / 自定义）按单张统一扣费，与原图分辨率和 size 请求值都无关。 尺寸限制：自定义尺寸须满足宽高均为 16 的倍数、长边 ≤ 3840、总像素数 ≤ 8,294,400，超出会返回 4xx。

比例	1K 推荐	2K 推荐	4K 推荐
1:1	`1024x1024`	`2048x2048`	`2880x2880`
4:3	`1536x1024`	`2048x1536`	`3264x2448`
3:4	`1024x1536`	`1536x2048`	`2448x3264`
16:9	`1792x1024`	`2048x1152`	`3840x2160`
9:16	`1024x1792`	`1152x2048`	`2160x3840`

例如：原图是 1024x1024，size 传 2048x2048 时，模型会按编辑指令重绘并输出 2K 图；size 传 3840x2160 时输出 4K 横屏图。三者计费一致。传 auto（或省略 size）时，输出会沿用参考图的宽高比——上例中原图是 1:1，就会得到 1:1 的结果，而不会被压成别的画幅。这一点与生成接口不同：生成接口没有参考图，auto 是按提示词语义挑画幅的。想改变画幅时再显式指定 size。

关于 n 参数 gpt-image-2 编辑接口支持 n > 1：一次请求即可返回并按张计费对应数量的编辑结果（n 取值 1–10）。同样适用于 gpt-image-1 / gpt-image-1.5，以及 nano-banana / nano-banana-2-lite / nano-banana-2 / nano-banana-pro 系列。注意 response_format=b64_json 仅支持 n=1，n>1 时请使用默认的 URL 返回。若其中部分图片生成失败，只会返回并计费成功的部分。

下面通过两个不同方位的真实示例感受 gpt-image-2 的编辑能力。

调用方式一：JSON + 图片 URL（推荐）

直接以 application/json 方式发送请求，image 字段填入一张图片的 URL，模型会去抓取该图片并按 prompt 进行编辑。例如，下面这张原图是用 gpt-image-2 生成的科普图鉴：

我们希望把它改成“夜间模式”配色。可以这样调用：

curl -X POST "https://api.acedata.cloud/openai/images/edits" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "image": "https://platform.cdn.acedata.cloud/gpt-image/5c9fa635-8794-4c6d-88f8-584d7f4716c6_0.png",
    "prompt": "Convert this infographic to dark mode: dark navy background, light cream text, deep gray rounded module cards with soft shadows. Keep all layout, structure, and module arrangement identical — only invert the color scheme.",
    "size": "1024x1536"
  }'

或者用 Python：

import requests

url = "https://api.acedata.cloud/openai/images/edits"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "gpt-image-2",
    "image": "https://platform.cdn.acedata.cloud/gpt-image/5c9fa635-8794-4c6d-88f8-584d7f4716c6_0.png",
    "prompt": "Convert this infographic to dark mode: dark navy background, light cream text, deep gray rounded module cards with soft shadows. Keep all layout, structure, and module arrangement identical — only invert the color scheme.",
    "size": "1024x1536"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

返回结果如下：

{
  "success": true,
  "task_id": "cb104e35-af1f-45be-9fac-b62e2b256753",
  "trace_id": "3e5c77c6-6c2e-4bba-a42d-98ea049b58a8",
  "created": 1777048863,
  "data": [
    {
      "revised_prompt": "Convert this infographic to dark mode: dark navy background, light cream text, deep gray rounded module cards with soft shadows. Keep all layout, structure, and module arrangement identical — only invert the color scheme.",
      "url": "https://platform.cdn.acedata.cloud/gpt-image/cb104e35-af1f-45be-9fac-b62e2b256753_0.png"
    }
  ],
  "elapsed": 83.859
}

编辑之后的图片如下：

可以看到模块结构、信息分区、字体排版都被严格保留，只有配色被反转为深色主题。

提示：image 字段也支持传入一个数组，例如 "image": ["url1", "url2", "url3"]，最多可同时传入 16 张参考图，让模型综合参考多张图片进行编辑。

base64 直传：image（及数组里的每一项）除了 URL，也可以是 base64 —— data:image/png;base64,... 或裸 base64 都行，适合本地图片不想先上传图床的场景。例如：

import base64, requests
b64 = base64.b64encode(open("input.png", "rb").read()).decode()
payload = {
    "model": "gpt-image-2",
    "image": f"data:image/png;base64,{b64}",
    "prompt": "Convert this infographic to dark mode.",
    "size": "1024x1536"
}
requests.post("https://api.acedata.cloud/openai/images/edits", json=payload,
              headers={"authorization": "Bearer {token}"})

调用方式二：JSON + 多张参考图

gpt-image-2 支持同时参考多张图片来生成最终结果，例如把多张产品照合成到一张礼物篮中：

payload = {
    "model": "gpt-image-2",
    "image": [
        "https://example.com/item1.png",
        "https://example.com/item2.png",
        "https://example.com/item3.png"
    ],
    "prompt": "Combine all the items above into a single 'Relax & Unwind' gift basket on a clean white background, photorealistic, soft natural lighting.",
    "size": "1024x1024"
}

场景示例：换风格 + 保持结构

下面是另一个例子，把一张木质书架替换为现代浮架，但严格保留每层书本的数量和排列。原图（用 gpt-image-2 生成的木质书架）：

调用：

payload = {
    "model": "gpt-image-2",
    "image": "https://platform.cdn.acedata.cloud/gpt-image/141970f0-65fb-4ec8-ab7d-9be173641350_0.png",
    "prompt": "Replace the wooden bookshelf with a sleek modern white floating shelf mounted on a pastel blue wall. Keep the exact same arrangement of books (1 book on top, 3 in middle, 7 on bottom). Add a small potted succulent on the top shelf next to the book. Bright airy daylight from the left.",
    "size": "1024x1024"
}

编辑结果（task_id: e9544dba-727e-44a2-81e1-223d49869380）：

可以看到风格和环境都按提示词进行了完整替换，但每层书本的数量（1 / 3 / 7）依旧严格保留，并且按要求增加了一盆多肉植物。

调用方式三：multipart/form-data（兼容 OpenAI SDK）

如果你已经在使用官方 OpenAI Python SDK，原有的 multipart/form-data 上传方式同样适用，只需把 model 改为 gpt-image-2：

import base64
from openai import OpenAI
client = OpenAI()

result = client.images.edit(
    model="gpt-image-2",
    image=[open("test.png", "rb")],
    prompt="Convert this image to dark mode while keeping the layout intact."
)

image_base64 = result.data[0].b64_json
image_bytes = base64.b64decode(image_base64)
with open("edited.png", "wb") as f:
    f.write(image_bytes)

使用 SDK 时需要先导入两个环境变量，OPENAI_BASE_URL 设为 https://api.acedata.cloud/openai，OPENAI_API_KEY 设为申请到的 token：

export OPENAI_BASE_URL=https://api.acedata.cloud/openai
export OPENAI_API_KEY={token}

Nano Banana 系列模型

nano-banana 系列在编辑场景下同样接入了 /openai/images/edits，把 model 改为下表中的任意一个即可。

模型	计费（Credits / 次）	适用场景
`nano-banana`	0.14	普通图像编辑，速度最快、成本最低
`nano-banana-2-lite`	0.14	Gemini 3.1 轻量图像模型，仅支持 1K，低延迟编辑
`nano-banana-2`	0.28	质量与细节明显提升
`nano-banana-pro`	0.35	系列中的旗舰，结构、文字、风格保留最佳

重要：参数支持范围 Nano Banana 通过适配层接入 OpenAI 协议，仅支持以下参数：model、prompt、image、n。

image 既可以通过 multipart/form-data 上传文件（本地文件会自动转为 base64 处理），也可以通过表单字段直接传图片 URL 字符串。

不支持 mask、size、response_format 等参数；填了也会被忽略。n > 1 则受支持（1–10），会返回并按张计费对应数量的编辑结果。

返回结构遵循 OpenAI 格式（data[].url），但 created 固定为 0，且不会返回 b64_json，revised_prompt 始终等于原始 prompt。

通过表单 + 图片 URL 调用

curl -X POST "https://api.acedata.cloud/openai/images/edits" \
  -H "Authorization: Bearer {token}" \
  -F "model=nano-banana" \
  -F "prompt=add a green leaf on top of the apple" \
  -F "image=https://platform.cdn.acedata.cloud/nanobanana/6870b330-65c4-436c-bb80-819fdae7a7a4.png"

返回结果如下：

{
  "created": 0,
  "data": [
    {
      "url": "https://platform.cdn.acedata.cloud/nanobanana/311e95b6-5eb1-4c4a-8ee6-0cb03ee44f61.jpeg",
      "revised_prompt": "add a green leaf on top of the apple"
    }
  ]
}

编辑后的图片：

通过表单 + 本地文件调用

import requests

url = "https://api.acedata.cloud/openai/images/edits"

headers = {
    "authorization": "Bearer {token}"
}

files = {
    "image": open("apple.png", "rb"),
}
data = {
    "model": "nano-banana-pro",
    "prompt": "add a green leaf on top of the apple"
}

response = requests.post(url, headers=headers, files=files, data=data)
print(response.text)

异步回调

callback_url 异步回调机制对 nano-banana 同样有效，调用流程与其它模型完全一致，详见下文异步回调一节。

基本使用

接下来就可以使用代码进行调用，下方是通过CURL进行调用：

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.acedata.cloud/v1/images/edits" \
  -H "Authorization: Bearer {token}" \
  -F "model=gpt-image-1" \
  -F "image[]=@test.png" \
  -F 'prompt=Create a lovely gift basket with these this items in it'

在第一次使用该接口时，我们至少需要填写四个内容，一个是 authorization，直接在下拉列表里面选择即可。另一个参数是 model， model 就是我们选择使用 OpenAI 官网模型类别，这里我们主要有 1 种模型，详情可以看我们提供的模型。还有一个参数是prompt，prompt 是我们输入要生成图像的提示词。最后一个参数是image，这个参数需要编辑的图片路径，需要编辑的图片如下图所示：

提示：image[] 可以重复出现多次以上传多张参考图，例如 -F "image[]=@a.png" -F "image[]=@b.png"，GPT Image 系列模型最多支持 16 张（每张不超过 50MB，格式为 png/webp/jpg）。超出数量会返回 400。

相同调用效果的Python 样例调用代码：

import base64
from openai import OpenAI
client = OpenAI()

prompt = """
Generate a photorealistic image of a gift basket on a white background 
labeled 'Relax & Unwind' with a ribbon and handwriting-like font, 
containing all the items in the reference pictures.
"""

result = client.images.edit(
    model="gpt-image-1",
    image=[
        open("test.png", "rb")
    ],
    prompt=prompt
)

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

# Save the image to a file
with open("gift-basket.png", "wb") as f:
    f.write(image_bytes)

使用Python调用全我们需要先导入俩个环境变量，一个OPENAI_BASE_URL，可以设置为https://api.acedata.cloud/openai，还有一个使用凭证变量OPENAI_API_KEY，这个值是从authorization获取到的，在Mac OS可以通过以下命令设置环境变量：

export OPENAI_BASE_URL=https://api.acedata.cloud/openai
export OPENAI_API_KEY={token} 

调用之后，我们发现会在当前目录下生成一张图片gift-basket.png，具体的结果如下：

这样我们就完成了对图片的编辑操作，目前 Edits 接口共支持 gpt-image-1 和 gpt-image-2 两种模型，其中 gpt-image-2 是当前推荐使用的模型，详见上文 GPT-Image-2 模型一节。

异步回调

由于 OpenAI Images Edits API 编辑图片的时间可能相对较长，如果 API 长时间无响应，HTTP 请求会一直保持连接，导致额外的系统资源消耗，所以本 API 也提供了异步回调的支持。整体流程是：客户端发起请求的时候，额外指定一个 callback_url 字段，客户端发起 API 请求之后，API 会立马返回一个结果，包含一个 task_id 的字段信息，代表当前的任务 ID。当任务完成之后，编辑图片的结果会通过 POST JSON 的形式发送到客户端指定的 callback_url，其中也包括了 task_id 字段，这样任务结果就可以通过 ID 关联起来了。下面我们通过示例来了解下具体怎样操作。首先，Webhook 回调是一个可以接收 HTTP 请求的服务，开发者应该替换为自己搭建的 HTTP 服务器的 URL。此处为了方便演示，使用一个公开的 Webhook 样例网站 https://webhook.site/，打开该网站即可得到一个 Webhook URL，如图所示：

将此 URL 复制下来，就可以作为 Webhook 来使用，此处的样例为 https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab。接下来，我们可以设置字段 callback_url 为上述 Webhook URL，同时填入相应的参数，如以下代码所示：

curl -X POST "https://api.acedata.cloud/v1/images/edits" \
  -H "Authorization: Bearer {token}" \
  -F "model=gpt-image-1" \
  -F "image[]=@test.png" \
  -F "prompt=Create a lovely gift basket with these items in it" \
  -F "callback_url=https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab"

调用之后，可以发现会立即得到一个结果，如下：

{
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c"
}

稍等片刻，我们可以在 Webhook URL 上观察到编辑图片的结果，内容如下：

{
  "success": true,
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c",
  "trace_id": "9b4b1ff3-90f2-470f-b082-1061ec2948cc",
  "data": {
    "created": 1721626477,
    "data": [
      {
        "b64_json": "iVBORw0KGgo..."
      }
    ]
  }
}

可以看到结果中有一个 task_id 字段，data 字段包含了和同步调用一样的图片编辑结果，通过 task_id 字段即可实现任务的关联。

错误处理

在调用 API 时，如果遇到错误，API 会返回相应的错误代码和信息。例如：

400 token_mismatched：Bad request, possibly due to missing or invalid parameters.
400 api_not_implemented：Bad request, possibly due to missing or invalid parameters.
401 invalid_token：Unauthorized, invalid or missing authorization token.
429 too_many_requests：Too many requests, you have exceeded the rate limit.
500 api_error：Internal server error, something went wrong on the server.

错误响应示例

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

结论

通过本文档，您已经了解了如何使用 OpenAI Images Edits API 轻松使用官方 OpenAI 的图像编辑功能。希望本文档能帮助您更好地对接和使用该 API。如有任何问题，请随时联系我们的技术支持团队。

入门

核心概念

AI 聊天

AI 图像

AI 视频

AI 音频

网络与数据

验证码

身份验证

代理

高级

OpenAI Images Edits API 申请及使用

申请流程

GPT-Image-2 模型

线路变体（`:official` / `:reverse`）

支持的 `size` 取值

调用方式一：JSON + 图片 URL（推荐）

调用方式二：JSON + 多张参考图

场景示例：换风格 + 保持结构

调用方式三：multipart/form-data（兼容 OpenAI SDK）

Nano Banana 系列模型

通过表单 + 图片 URL 调用

通过表单 + 本地文件调用

异步回调

基本使用

异步回调

错误处理

错误响应示例

结论

​申请流程

​GPT-Image-2 模型

​线路变体（:official / :reverse）

​支持的 size 取值

​调用方式一：JSON + 图片 URL（推荐）

​调用方式二：JSON + 多张参考图

​场景示例：换风格 + 保持结构

​调用方式三：multipart/form-data（兼容 OpenAI SDK）

​Nano Banana 系列模型

​通过表单 + 图片 URL 调用

​通过表单 + 本地文件调用

​异步回调

​基本使用

​异步回调

​错误处理

​错误响应示例

​结论

申请流程

GPT-Image-2 模型

线路变体（`:official` / `:reverse`）

支持的 `size` 取值

调用方式一：JSON + 图片 URL（推荐）

调用方式二：JSON + 多张参考图

场景示例：换风格 + 保持结构

调用方式三：multipart/form-data（兼容 OpenAI SDK）

Nano Banana 系列模型

通过表单 + 图片 URL 调用

通过表单 + 本地文件调用

异步回调

基本使用

异步回调

错误处理

错误响应示例

结论