OpenAI Images Edits API 申请及使用

OpenAI 图片编辑服务，可以传入任意多张图片和指令，输出修改之后的图片。目前接口同时支持 dall-e-2、gpt-image-1、最新的 gpt-image-2，以及通过同一接口接入的 nano-banana / 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，无需先把图片下载到本地，非常适合服务端流水线接入。
支持高分辨率重绘：可以传入一张 1K 原图，通过 size 参数请求 2K / 4K 输出，模型会在编辑过程中同时完成放大。

支持的 `size` 取值

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

比例	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 或省略则由模型自行选择。三者计费一致。

关于 n 参数 gpt-image-2 编辑接口目前不支持 n > 1：该参数会被静默忽略，无论传 n=1 还是 n=10，单次请求都只会返回 1 张图，并且只按 1 张计费。如果你需要一次拿到多张候选编辑结果，请自行并发发起多次请求。该限制同样适用于 gpt-image-1 / gpt-image-1.5，以及 nano-banana / nano-banana-2 / nano-banana-pro 系列。dall-e-2 是目前唯一原生支持 n > 1 的编辑模型。

下面通过两个不同方位的真实示例感受 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 张参考图，让模型综合参考多张图片进行编辑。

调用方式二：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`	0.28	质量与细节明显提升
`nano-banana-pro`	0.35	系列中的旗舰，结构、文字、风格保留最佳

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

image 既可以通过 multipart/form-data 上传文件（worker 内部会转成 data:<mime>;base64,... 传给上游），也可以通过表单字段直接传图片 URL 字符串。

不支持 mask、n、size、response_format 等参数；填了也会被忽略。

返回结构遵循 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，这个参数需要编辑的图片路径，需要编辑的图片如下图所示：

相同调用效果的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 接口共支持三种模型：dall-e-2、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。如有任何问题，请随时联系我们的技术支持团队。

​申请流程

​GPT-Image-2 模型

​支持的 size 取值

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

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

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

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

​Nano Banana 系列模型

​通过表单 + 图片 URL 调用

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

​异步回调

​基本使用

​异步回调

​错误处理

​错误响应示例

​结论

申请流程

GPT-Image-2 模型

支持的 `size` 取值

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

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

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

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

Nano Banana 系列模型

通过表单 + 图片 URL 调用

通过表单 + 本地文件调用

异步回调

基本使用

异步回调

错误处理

错误响应示例

结论