TokenLab 上的 GPT Image Edit API：正確端點與圖像輸入格式

圖像編輯是 AI 產品介面中要求較高的部分之一：使用者上傳照片、描述修改內容，並期待獲得結果。涉及多張來源圖像、大尺寸畫布或較複雜提示詞的編輯，其處理時間往往超過一般同步 HTTP 呼叫所能輕鬆承受的範圍。本指南將介紹正確的 TokenLab 端點、兩種支援的圖像輸入格式、多圖編輯，以及針對慢速請求的非同步處理路徑。

端點

圖像編輯的端點為 POST /v1/images/edits——請注意複數形式的 edits。（常見的錯誤是寫成 /images/edit，這不是官方文件中記錄的路徑。）

該端點支援兩種請求格式：

• 相容於 OpenAI 的 multipart/form-data 上傳流程。
• 提供 image_url、image_urls 或官方 images[] 參考（適用於支援的圖生圖系列）的 JSON 請求。

完整的請求與回應欄位請參閱編輯圖像 API 參考。

gpt-image-2 在此接受的內容

• Multipart image 上傳。
• JSON 的 image_url 或 image_urls。
• 官方 images[] 參考，其中每個物件必須恰好包含 image_url 或 file_id 其中之一。
• 每個請求最多支援 16 張來源圖像。

在撰寫程式碼前，有幾項限制值得留意：

• gpt-image-2 編輯不接受 resolution；請使用 size 指定輸出尺寸（可為 auto 或 WIDTHxHEIGHT，維度必須是 16 的倍數，最長邊最多 3840px，長短邊比例最多 3:1）。
• background 接受 auto 或 opaque；不支援 transparent。
• input_fidelity 不是 gpt-image-2 支援的欄位；傳入此參數將傳回 400 unsupported_parameter。
• 對於 JSON 請求，請恰好提供 image_url、image_urls 或 images 其中之一。每個 images[] 物件必須恰好包含 image_url 或 file_id 其中之一。file_id 的值必須先透過 /v1/files 建立。
• Nano Banana 參考圖像請求應發送至 /v1/images/generations，並搭配 operation: "image-to-image" 與 image_urls——而非發送至 /v1/images/edits。

Multipart 上傳與 JSON 圖像參考的比較

兩者均適用於 gpt-image-2。請根據您的圖像位元組目前所在的位置進行選擇。

Multipart——當應用程式持有該檔案時使用此方式，無論是來自使用者上傳還是已產生的素材。重複使用 image 欄位即可傳送多個來源。檔案必須為 PNG、JPEG 或 WebP 格式，每個檔案上限為 50 MiB。

curl -X POST "https://api.tokenlab.sh/v1/images/edits" \
  -H "Authorization: Bearer sk-your-api-key" \
  -F "model=gpt-image-2" \
  -F "image=@subject.png" \
  -F "image=@background.png" \
  -F "prompt=Combine the subject with the new background." \
  -F "size=1024x1024"

JSON 圖像 URL——當圖像已經位於公開 URL 上，或者您在先前的 TokenLab 請求中產生了圖像且已擁有 URL 時，請使用此方式。

curl -X POST "https://api.tokenlab.sh/v1/images/edits" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "images": [
      {"image_url": "https://example.com/subject.png"},
      {"image_url": "https://example.com/background.png"}
    ],
    "prompt": "Combine the subject with the new background.",
    "size": "1024x1024",
    "async": true
  }'

遠端 URL 必須是公開的 http/https，不得內嵌憑證或片段，且不得解析至 localhost、私有或保留 IP 範圍。TokenLab 會擷取這些位元組並將其作為 multipart image 部分傳遞給模型。單張圖像限制為 50 MiB；單一請求中透過 URL 擷取圖像的總上限為 200 MiB；擷取逾時為 30 秒；最多支援追蹤 3 次重新導向。

多圖編輯與非同步輪詢

多圖編輯是使用 async: true 最明確的場景。透過同步呼叫發送多張圖像以及複雜的指示集合，意味著必須在模型處理期間一直保持連線開啟。在 gpt-image-2（以及官方 FLUX/BFL 編輯模型）上設定 async: true 即可改為接收一個任務：

{
  "created": 1706000000,
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "data": []
}

輪詢傳回的 poll_url，或備用方式為呼叫 GET /v1/tasks/{task_id}。狀態包含 pending、processing、completed 及 failed。已完成的圖像任務會傳回 data[].url。每 3–5 秒檢查一次即可；在達到終止狀態時應停止輪詢，而非繼續查詢。

curl "https://api.tokenlab.sh/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" \
  -H "Authorization: Bearer sk-your-api-key"

無論請求的 response_format 為何，非同步編輯任務均會傳回最終的圖像 URL。如果您需要原始的 b64_json，請使用同步請求。

計費系統可能會在建立任務時預扣預估金額；已完成的任務將依實際用量計費，而失敗或逾時的任務則會釋放預扣額度或進行退款。完整的生命週期請參閱非同步任務與輪詢，回應欄位請參閱取得圖像狀態。

何時使用各模式

在以下情況使用 async: true：

• 您在單一請求中傳送多張來源圖像。
• 您的提示詞或指示集合較為複雜，導致產生時間無法預測。
• 您是在背景工作、佇列或批次處理中執行編輯，而非即時面對使用者的請求。

在以下情況保持同步：

• 您正在進行單張圖像編輯且提示詞簡短。
• 您的用戶端偏好快速失敗而非輪詢。

對於同步呼叫，請將 HTTP 用戶端逾時設定為至少 120s；高解析度或高品質的請求可能需要將近一分鐘或更長時間。如果建立時的回應仍傳回 status: "pending"、task_id 或 poll_url，請切換至傳回的輪詢流程。

可能遇到的輸入錯誤

遠端圖像擷取失敗會在生成開始前作為輸入錯誤傳回。無法存取的 URL、逾時、403/404 回應、私有或內部主機、URL 中的憑證或片段、非圖像內容、不支援的格式以及超出大小限制違規等，均會傳回 400 或 413，並指出引發問題的 image_url 或 image_urls[n]。對於私有或受標頭保護的素材，請直接上傳 multipart image 檔案，或建立 /v1/files 參考並作為 images[].file_id 傳入。

xAI Grok Imagine 圖像編輯模型（例如 grok-imagine-image 與 grok-imagine-image-quality）使用相同的輸入欄位，但來源圖像上限為 3 張；超過此數量將傳回 400 too_many_images。

整合檢查清單

• 目標端點為 POST /v1/images/edits 並明確傳送 model。
• 根據圖像目前所在位置選擇 multipart 上傳或 JSON 參考。
• 在 JSON 請求中恰好傳送 image_url、image_urls 或 images[] 其中之一；每個 images[] 項目必須恰好包含 image_url 或 file_id 其中之一。
• 對於多圖或繁重的編輯請使用 async: true；輪詢傳回的 poll_url，直到任務達到 completed 或 failed。
• 對於同步請求，將用戶端逾時設定為至少 120 秒，若收到 pending 回應則依據 poll_url 進行處理。
• 當用戶端發生逾時，在重試建立請求前先檢查是否已建立任務，以避免重複扣費。

開始使用

查詢 GET /v1/models?recommended_for=image 以查看目前的圖像模型，然後在發送請求前開啟模型的詳細資訊頁面確認其支援的操作與請求欄位。從控制台建立 API 金鑰，即可使用您自己的圖像測試編輯端點。