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

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

编辑后的图片：

通过表单 + 本地文件调用

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 -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。

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

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可以通过以下命令设置环境变量：

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

錯誤響應示例

{
  "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 圖片編輯 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 调用

通过表单 + 本地文件调用

异步回调

基本使用

异步回调

錯誤處理

錯誤響應示例

結論