AI 圖像編輯 API 選擇指南：Endpoints、Inputs 與計費單位

最好的 AI 圖像編輯 API 通常不是展示效果最好的那一個，而是其端點、輸入形狀與計費單位最符合您產品實際編輯需求的那個。遮罩編輯 (Mask edits)、參考引導的圖生圖 (Reference-guided image-to-image) 以及特定模型的編輯操作並不共享同一個合約。我們於 2026 年 10 月 3 日閱讀了 TokenLab 的編輯文件與即時模型頁面，以下所有內容均來自這些頁面。圖像端點不會為您選擇預設模型，因此請務必明確發送 model 參數。

重點摘要

• 基於遮罩的編輯請使用 POST /v1/images/edits。Nano Banana 參考編輯請使用 POST /v1/images/generations 並設定 operation: "image-to-image"。
• 計費單位各不相同。gpt-image-2 與 Gemini 圖像模型按 token 計費，而 flux-kontext-pro 則按請求計費，每次 $0.04。
• 現有證據中不包含關於修復品質 (inpainting quality)、文字渲染、風格保留或產品拍攝保真度的基準測試。請務必使用您自己的圖像進行測試。
• 若模型支援，長篇或多圖編輯應使用 async: true。請儲存任務 ID (task ID) 並從 Usage 中讀取最終費用。
• 在提交請求前，請檢查每個模型的頁面以確認其價格與單位，因為即時 API 會有所變動。

各使用場景的入門首選

這些選擇遵循已記錄的合約與列出的價格。它們並非品質排名，因為現有證據中沒有編輯品質的基準測試。請將它們視為您測試集中的首選模型。

您的需求	入門首選	原因	來源
基於遮罩的修復 (Inpainting)	gpt-image-2	這是唯一明確說明遮罩合約的模型：PNG 格式、相同尺寸、透明區域即為編輯範圍。	Edit Image 參考文件, 2026-10-03
單次編輯包含多張來源圖像	gpt-image-2	文件記錄限制為 16 張來源圖像。Grok Imagine 編輯模型上限為 3 張。	Edit Image 參考文件, 2026-10-03
最便宜的固定價格參考編輯	grok-imagine-image	每次請求 $0.02，是我們表格中最低的固定價格。	即時模型 API, 2026-10-03
保留產品形狀，更換場景	nano-banana-pro	文件中的參考範例正是執行此操作，價格為每張圖像 $0.067。	Create Image 參考文件, 2026-10-03
編輯後的圖像內含文字	無首選	現有證據中沒有任何編輯模型的文字渲染數據。	n/a

最佳 AI 圖像編輯 API 候選名單：模型、單位與價格

下表列出了我們證據集中所有被列為具備編輯能力，或在編輯文件中被指名為編輯模型的模型。所有價格均為 TokenLab 美元公開價格。即時 API 報告的定價更新於 2026-10-02T16:53:30.068Z，我們於 2026-10-03 觀察了每個頁面。

模型 ID	即時 API 列出的功能	計費單位	TokenLab 價格 (USD)	來源	觀察日期
gpt-image-2	文字轉圖像 (編輯功能記錄於 /v1/images/edits)	per_token	$3.50/1M 文字輸入, $5.60/1M 圖像輸入, $21/1M 圖像輸出；快取文字輸入 $0.875/1M	即時模型 API	2026-10-03
flux-kontext-pro	圖像編輯, 圖生圖, 文字轉圖像	per_request	$0.04	即時模型 API	2026-10-03
flux-pro-1.0-fill	圖生圖	per_image	$0.035	即時模型 API	2026-10-03
flux-2-pro	圖生圖, 文字轉圖像	per_image	$0.03	即時模型 API	2026-10-03
nano-banana-pro	圖像編輯, 圖生圖, 文字轉圖像	per_image	$0.067 (價格區間總結最高至 $0.12)	即時模型 API	2026-10-03
gemini-3-pro-image	圖生圖, 文字轉圖像, 視覺	per_token	$1/1M 輸入, $6/1M 文字輸出, $60/1M 圖像輸出	即時模型 API	2026-10-03
gemini-3.1-flash-image	圖生圖, 文字轉圖像, 視覺	per_token	$0.25/1M 輸入, $1.50/1M 文字輸出, $30/1M 圖像輸出	即時模型 API	2026-10-03
grok-imagine-image	圖生圖, 文字轉圖像	per_request	$0.02	即時模型 API	2026-10-03

當我們比對這些頁面時，發現了三個不一致之處。即時 API 將 gpt-image-2 列為僅支援文字轉圖像，但 Edit Image 參考文件 卻指出它在 /v1/images/edits 上受到支援。flux-pro-1.0-fill 與 flux-2-pro 的即時頁面列出了圖生圖功能，而我們的目錄快照則將兩者標記為圖像編輯。此外，nano-banana-pro 列出了圖像編輯功能，但其文件卻將其導向 /v1/images/generations。我們將文件視為路由的權威，將即時 API 視為價格的權威。

對於固定價格模型，粗略估算只需簡單乘法。這些僅為估算值而非報價，且假設每個完成的請求僅計費一次：

• 100 次 grok-imagine-image 編輯：100 × $0.02 = $2.00。
• 100 次 flux-2-pro 編輯：100 × $0.03 = $3.00。
• 100 次 flux-pro-1.0-fill 編輯：100 × $0.035 = $3.50。
• 100 次 flux-kontext-pro 編輯：100 × $0.04 = $4.00。

現有證據未提供按 token 計費模型的單次編輯估算。gpt-image-2 會計算文字輸入、圖像輸入、回報的快取輸入以及圖像輸出 token，因此它並非固定按張計費的模型。現有證據中沒有典型編輯的 token 計數。請執行幾次實際編輯並在 Usage 中讀取費用，如 Billing guide 所述。nano-banana-pro 的價格區間暗示了解析度分級，但證據中並未將分級對應到價格。

編輯端點接受的內容與未記錄的內容

Edit Image 參考文件 (觀察於 2026-10-03) 支援 OpenAI 相容的 multipart 流程與 JSON 請求。以下是它對 gpt-image-2 的說明：

• 輸入圖像。 發送 multipart image、JSON image_url / image_urls，或官方的 images[] 物件。每個 images[] 物件必須包含 image_url 或 file_id 其中之一。請先透過 /v1/files 建立 file_id 值。
• 多重參考。 最多 16 張來源圖像，每張均為 PNG、JPEG 或 WebP 格式，最大 50 MiB。在 multipart 請求中重複 image 欄位。在 JSON 中，請僅提供 image_url、image_urls 或 images 其中之一。
• 遮罩。 一個小於 50 MiB 的 PNG 檔案，尺寸需與來源圖像相同。完全透明的區域標記了編輯應用的位置。在 JSON 中，mask 可以是一個物件，且必須包含 image_url 或 file_id 其中之一。
• 輸出。 size 接受 auto 或 WIDTHxHEIGHT。尺寸必須是 16 的倍數，最長邊最多 3840px，長寬比最多 3:1，總像素介於 655,360 與 8,294,400 之間。請勿發送 resolution。background 接受 auto 或 opaque，不接受 transparent。
• 拒絕的欄位。 input_fidelity 不支援 gpt-image-2，發送該欄位會回傳 400 unsupported_parameter。
• 遠端 URL。 必須是公開的 http/https，且不含嵌入的憑證或片段。不得解析為 localhost、私有或保留位址範圍。限制為每張圖像 50 MiB，每個請求總計 200 MiB (包含遮罩)，30 秒擷取逾時，最多 3 次重新導向。擷取的內容必須是真實的 PNG、JPEG 或 WebP。

Grok Imagine 編輯模型 (grok-imagine-image, grok-imagine-image-quality) 使用相同的輸入欄位，但來源圖像上限為 3 張。超過此限制的請求會失敗並回傳 400 too_many_images。

Nano Banana 則不同。文件指出 nano-banana-2 與 nano-banana-pro 在 /v1/images/generations 上接收參考圖像請求，並使用 operation: "image-to-image" 與 image_urls。它們不屬於 /v1/images/edits。頂層的 images[] 與 file_id 是編輯流程的格式，在 generations 端點會被拒絕。以下是 nano-banana-pro 的文件範例，它接受 resolution：

{
  "model": "nano-banana-pro",
  "prompt": "Keep the product shape, change the background to a bright studio setup",
  "operation": "image-to-image",
  "image_urls": ["https://example.com/input/product.png"],
  "aspect_ratio": "1:1",
  "resolution": "2k"
}

對於 Google 圖像系列，Create Image 參考文件 建議優先使用 aspect_ratio，並僅在模型支援的情況下發送 resolution (1k, 2k, 4k)。nano-banana-2 的模型細節連結於此，但證據集中未包含其價格。

證據中未記錄的內容：

• 除了 gpt-image-2 之外，是否有其他模型在 /v1/images/edits 上接受 mask，包括 flux-pro-1.0-fill 與 stability-inpaint。
• 當您發送多張來源圖像時，單一遮罩如何應用。
• FLUX 與 Nano Banana 模型的來源圖像限制。
• 多圖請求中的圖像順序是否會影響結果。

在基於這些模型進行開發前，請先閱讀該模型的詳細頁面。

一個完整的編輯請求

此請求僅使用 gpt-image-2 的已記錄欄位：來源圖像、遮罩、提示詞、size 與 async。它遵循 Edit Image 參考文件 中的 multipart 範例。

curl -X POST "https://api.tokenlab.sh/v1/images/edits" \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -F "model=gpt-image-2" \
  -F "image=@source.png" \
  -F "mask=@mask.png" \
  -F "prompt=A sunlit indoor lounge area with a pool" \
  -F "n=1" \
  -F "size=1024x1024" \
  -F "async=true"

使用 async=true 時，回應會包含 status: "pending"、task_id 與 poll_url，而 data 欄位保持為空。若要進行同步呼叫，請移除 async 行。同步呼叫預設會回傳 data[].url，若您設定了 response_format，則會回傳 data[].b64_json。請按如下方式輪詢任務：

curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $TOKENLAB_API_KEY"

gpt-image-2 的模型細節位於其模型頁面。對於同步呼叫，請將 HTTP 客戶端逾時設定為至少 120 秒，因為高解析度請求可能需要接近一分鐘或更長時間。

按任務選擇最佳 AI 圖像編輯 API

證據中說明了路由、輸入與價格。由於不包含編輯品質的基準測試，因此以下所有「哪個更好」的問題都需要您自行準備測試集。

修復 (Inpainting)。 gpt-image-2 是唯一在文件中明確說明遮罩合約的模型。目錄中也列出了專用的區域與結構工具：stability-inpaint、stability-control-structure 與 stability-control-sketch。對於填充與上下文編輯，有每張圖像 $0.035 的 flux-pro-1.0-fill 以及每次請求 $0.04 的 flux-kontext-pro。證據中並未說明哪一個產生的接縫更乾淨。

風格保留編輯。 文件中的參考範例保留了產品形狀並更改周圍環境。這是 nano-banana-pro 在 /v1/images/generations 上的模式。flux-kontext-pro 列出了圖像編輯功能。兩者在此均未針對身份或風格保留進行基準測試。

圖像中的文字。 現有證據中沒有任何編輯模型的文字渲染資訊。ideogram-edit-v3 與 ideogram-reframe-v3 存在於目錄中，但我們未發現文字品質數據。請使用您自己的文案、字體與語言進行測試。

產品拍攝。 想像一個目錄團隊需要更換數千張產品照的背景。工具類模型是自然的優先選擇：image-background-remover、image-upscaler 與 stability-upscale-fast。它們的定價與輸入規則不在我們的證據中，因此請閱讀每個模型的頁面。對於生成式背景更換，固定的按請求定價使批次成本易於預測。按 token 定價則取決於圖像大小與輸出。

輸入要求是針對每個模型而非每個提供者。有些模型需要一張來源圖像加上提示詞，有些需要遮罩，有些則需要結構輸入。請在每個模型的詳細頁面上檢查其支援的操作與請求欄位。您可以在 模型目錄 中瀏覽目前的選項。

非同步處理與編輯成本確認

Image generation guide 與 Async jobs guide (均觀察於 2026-10-03) 描述了此流程。async: true 已記錄於 gpt-image-2 與官方 FLUX/BFL 編輯模型中。建立請求的回應會回傳 status: "pending"、task_id 與 poll_url。當 poll_url 存在時請輪詢該 URL，或使用 GET /v1/tasks/{id} 進行固定 URL 輪詢。狀態包括 pending、processing、completed 與 failed。文件建議針對長媒體任務每 5–10 秒檢查一次，並在達到終止狀態時停止。

四個細節最容易導致錯誤：

• 即使任務失敗，狀態讀取仍會回傳 HTTP 200。請根據 status 以及 error_details.code 與 type 來判斷失敗情況。
• 無論 response_format 為何，完成的非同步編輯都會回傳 URL。若您需要 b64_json，請使用同步請求。
• 在客戶端逾時後，請在重試建立呼叫前檢查任務是否存在。重試失敗的生成會建立一個新任務，並可能產生新的費用。
• 結果 URL 可能會作為媒體副本保留 30 天。請檢查每個項目的 media_retention.items 狀態與 expires_at。

關於成本，Billing guide 指出 Console 會在您確認付費生成前顯示最高估算值，而 Usage 則顯示最終費用。非同步任務在被接受時可能會預留其估算成本。已完成的任務僅計費一次，而失敗或逾時的任務會釋放或退還預留金額。交付選項也很重要。TokenLab Verified 使用 TokenLab 公開價格，Official 使用官方價格層級，而 Auto 會優先嘗試 Verified，然後是 Official。Models 頁面價格欄中的破折號表示沒有 Verified 優惠，並不代表該模型免費。API 金鑰的消費限額一旦達到，將回傳 402 Payment Required。

請將 request_id、task_id、poll_url、billing_transaction_id (若存在)、模型、端點以及您自己的工作 ID 一併儲存。實際上，該記錄能解決大多數計費不一致的問題。證據中僅記錄了 Seedance 影片任務的任務取消功能。圖像編輯的取消功能未被記錄，因此請在設計流程時考慮到這一點。

常見問題

我可以將遮罩發送給每個圖像編輯模型嗎？

證據中僅記錄了 gpt-image-2 在 /v1/images/edits 上使用遮罩。遮罩必須是小於 50 MiB 的 PNG，且尺寸需與來源相同，透明區域即為編輯範圍。對於其他模型，包括 flux-pro-1.0-fill，請在假設支援遮罩前檢查模型詳細頁面。

Nano Banana 編輯使用哪個端點？

請使用 POST /v1/images/generations 並設定 operation: "image-to-image" 與 image_urls。不支援將 Nano Banana 參考請求發送到 /v1/images/edits。也不要將頂層的 images[] 或 file_id 發送到 generations 端點。

為什麼我的 gpt-image-2 編輯回傳 400 unsupported_parameter？

最常見的原因是 input_fidelity，這不是 gpt-image-2 支援的欄位。此外，請移除 resolution 以及任何 background: "transparent" 的值。常見錯誤表格建議移除任何模型未記錄的欄位。

非同步編輯任務失敗時會被收費嗎？

Billing guide 指出失敗的任務不會被收費，其預留金額會被釋放或退還。已完成的任務僅計費一次，最終金額會出現在帶有 billing_transaction_id 的 Usage 中。如果任務結束後 Usage 仍未顯示任何內容，請攜帶 request ID 與 task ID 聯繫 support@tokenlab.sh。

若要執行上述請求，請在 Console → API Keys 下建立 API 金鑰（金鑰限制說明於 Billing guide），將其匯出為 TOKENLAB_API_KEY，並將您的範例編輯與 Usage 中的最終成本進行比對。