> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI Images Edits API 申请及使用

> OpenAI generation 集成指南 - Ace Data Cloud

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 控制台](https://platform.acedata.cloud/console/applications) 获取您的 API Token，留作备用。

![](https://cdn.acedata.cloud/5hmkdg.jpg)

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

**一个 API Token 即可调用平台所有服务，无需为每个服务单独申请。** 首次申请会赠送免费额度，可免费体验；额度不足时可在 [控制台](https://platform.acedata.cloud/console/coin) 充值通用余额。

> 📘 完整文档：[OpenAI Images Edits API →](https://platform.acedata.cloud/documents/openai-images-edits)

## 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` 生成的科普图鉴：

<p>
  <img src="https://platform.cdn.acedata.cloud/gpt-image/5c9fa635-8794-4c6d-88f8-584d7f4716c6_0.png" width="500" className="m-auto" />
</p>

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

```shell theme={null}
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：

```python theme={null}
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)
```

返回结果如下：

```json theme={null}
{
  "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
}
```

编辑之后的图片如下：

<p>
  <img src="https://platform.cdn.acedata.cloud/gpt-image/cb104e35-af1f-45be-9fac-b62e2b256753_0.png" width="500" className="m-auto" />
</p>

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

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

> **base64 直传**：`image`（及数组里的每一项）除了 URL，也可以是 base64 —— `data:image/png;base64,...` 或裸 base64 都行，适合本地图片不想先上传图床的场景。例如：
>
> ```python theme={null}
> 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` 支持同时参考多张图片来生成最终结果，例如把多张产品照合成到一张礼物篮中：

```python theme={null}
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` 生成的木质书架）：

<p>
  <img src="https://platform.cdn.acedata.cloud/gpt-image/141970f0-65fb-4ec8-ab7d-9be173641350_0.png" width="500" className="m-auto" />
</p>

调用：

```python theme={null}
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`）：

<p>
  <img src="https://platform.cdn.acedata.cloud/gpt-image/e9544dba-727e-44a2-81e1-223d49869380_0.png" width="500" className="m-auto" />
</p>

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

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

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

```python theme={null}
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：

```shell theme={null}
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 调用

```shell theme={null}
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"
```

返回结果如下：

```json theme={null}
{
  "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"
    }
  ]
}
```

编辑后的图片：

<p>
  <img src="https://platform.cdn.acedata.cloud/nanobanana/311e95b6-5eb1-4c4a-8ee6-0cb03ee44f61.jpeg" width="500" className="m-auto" />
</p>

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

```python theme={null}
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 theme={null}
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。

<p>
  <img src="https://cdn.acedata.cloud/jw9iwu.png" width="500" className="m-auto" />
</p>

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

```python theme={null}
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可以通过以下命令设置环境变量：

```shell theme={null}
export OPENAI_BASE_URL=https://api.acedata.cloud/openai
export OPENAI_API_KEY={token} 
```

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

<p>
  <img src="https://cdn.acedata.cloud/574s8h.png" width="500" className="m-auto" />
</p>

这样我们就完成了对图片的编辑操作，目前 Edits 接口共支持 `gpt-image-1` 和 `gpt-image-2` 两种模型，其中 `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/，打开该网站即可得到一个](https://webhook.site/，打开该网站即可得到一个) Webhook URL，如图所示：

![](https://cdn.acedata.cloud/cjjfly.png)

将此 URL 复制下来，就可以作为 Webhook 来使用，此处的样例为 `https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab`。

接下来，我们可以设置字段 `callback_url` 为上述 Webhook URL，同时填入相应的参数，如以下代码所示：

```shell theme={null}
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"
```

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

```json theme={null}
{
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c"
}
```

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

```json theme={null}
{
  "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.

### 错误响应示例

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

## 结论

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