OpenAI 圖片編輯 API 申請及使用

OpenAI 圖片編輯服務，可以傳入任意多張圖片和指令，輸出修改之後的圖片。本文檔主要介紹 OpenAI Images Edits API 操作的使用流程，利用它我們可以輕鬆使用官方 OpenAI 圖像編輯功能。

申請流程

要使用 OpenAI Images Edits API，首先可以到 OpenAI Images Edits API 頁面點擊「Acquire」按鈕，獲取請求所需要的憑證：

如果你尚未登入或註冊，會自動跳轉到登入頁面邀請您來註冊和登入，登入註冊之後會自動返回當前頁面。在首次申請時會有免費額度贈送，可以免費使用該 API。

基本使用

接下來就可以使用代碼進行調用，下方是通過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。

非同步回調

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

Documentation Index

​申請流程

​基本使用

​非同步回調

​錯誤處理

​錯誤響應示例

​結論

申請流程

基本使用

非同步回調

錯誤處理

錯誤響應示例

結論