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，首先可以到 OpenAI Images Edits API 页面，或者识别下方二维码：

然后点击「Acquire」按钮，获取请求所需要的凭证：

如果你尚未登录或注册，会自动跳转到登录页面邀请您来注册和登录，登录注册之后会自动返回当前页面。

在首次申请时会有免费额度赠送，可以免费使用该 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。计费只分两个档位，与原图分辨率无关，只看 size 请求值：

• 1K 标准价：下表中任一 1K 推荐尺寸，或上游 1K 常见输出别名（1254x1254、1672x941、941x1672）。
• 其他档位（1.5×）：包括下表推荐的 2K / 4K 预设，以及你自定义传入的任意 WIDTHxHEIGHT。

上游对自定义尺寸的硬约束同样适用：宽高均为 16 的倍数、长边 ≤ 3840、总像素数 ≤ 8,294,400。

“

例如：原图是 1024x1024，size 传 2048x2048 时，模型会按编辑指令重绘并输出 2K 图，按“其他”档位计费；size 传 3840x2160 时输出 4K 横屏图，同样按“其他”计费；传 auto 或省略则按 1K 标准价计费。

“

关于 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 requestsurl = "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 base64from openai import OpenAIclient = 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_jsonimage_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/openaiexport OPENAI_API_KEY={token}

Nano Banana 系列模型

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

“

重要：参数支持范围

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 requestsurl = "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 base64from openai import OpenAIclient = 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_jsonimage_bytes = base64.b64decode(image_base64)# Save the image to a filewith 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/openaiexport 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。如有任何问题，请随时联系我们的技术支持团队。