> ## 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 圖片編輯 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": "將這個資訊圖轉換為深色模式：深海軍藍背景，淺奶油色文字，深灰色圓角模組卡片，帶有柔和的陰影。保持所有佈局、結構和模組排列不變——僅反轉顏色方案。",
    "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": "將這個資訊圖轉換為深色模式：深海軍藍背景，淺奶油色文字，深灰色圓角模組卡片，帶有柔和的陰影。保持所有佈局、結構和模組排列不變——僅反轉顏色方案。",
    "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": "將這個資訊圖轉換為深色模式：深海軍藍背景，淺奶油色文字，深灰色圓角模組卡片，帶有柔和的陰影。保持所有佈局、結構和模組排列不變——僅反轉顏色方案。",
      "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": "將這個資訊圖轉換為深色模式。",
>     "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": "將上述所有物品合併成一個單一的「放鬆與舒緩」禮物籃，背景為乾淨的白色，照片真實感，柔和的自然光。",
    "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": "將木質書架替換為一個光滑的現代白色浮架，安裝在淺藍色牆上。保持書本的確切排列（1 本在上面，3 本在中間，7 本在底部）。在頂層書架上增加一盆小型多肉植物。從左側進來的明亮自然光。",
    "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="將這張圖片轉換為深色模式，同時保持佈局不變。"
)

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=在苹果上方添加一片绿色叶子" \
  -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": "在苹果上方添加一片绿色叶子"
    }
  ]
}
```

编辑后的图片：

<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": "在苹果上方添加一片绿色叶子"
}

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=创建一个可爱的礼品篮，里面包含这些物品'
```

在第一次使用该接口时，我们至少需要填写四个内容，一个是 `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 = """
生成一个礼品篮的照片真实图像，背景为白色， 
标有“放松与放松”的字样，带有丝带和手写风格的字体， 
包含所有参考图片中的物品。
"""

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)

# 将图像保存到文件
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`：錯誤請求，可能是由於缺少或無效的參數。
* `400 api_not_implemented`：錯誤請求，可能是由於缺少或無效的參數。
* `401 invalid_token`：未授權，無效或缺少授權令牌。
* `429 too_many_requests`：請求過多，您已超過速率限制。
* `500 api_error`：內部伺服器錯誤，伺服器出現問題。

### 錯誤響應示例

```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。如有任何問題，請隨時聯繫我們的技術支持團隊。