Nano Banana API 指南：在 TokenLab 上進行圖像生成與編輯

Nano Banana API 在 TokenLab 上有三個定價模型 ID，其中最便宜的模型每張圖像的成本約為中間價位模型的一半。昂貴的錯誤通常不是模型選擇的問題，而是將編輯請求發送到了錯誤的端點，或是重試了已經建立任務的創建調用。本指南涵蓋了確切的 ID、一個可運行的文字轉圖像調用、參考圖像調用、非同步輪詢、預期錯誤以及費用設定方式。價格與欄位列表讀取於 2026-10-03，請在發佈前再次確認。

重點摘要

• 發送正確的 ID：nano-banana-2、nano-banana-2-lite 或 nano-banana-pro。顯示名稱並非請求別名。
• Nano Banana 的參考圖像工作需發送至 POST /v1/images/generations，並帶有 operation: "image-to-image" 與 image_urls。請勿發送至 /v1/images/edits 或 /v1/chat/completions。
• 我們在 2026-10-03 讀取的基礎價格分別為 lite、standard 與 pro ID 的每張圖像 $0.0168、$0.0335 與 $0.067 美元。每個模型都有價格區間，請在「使用量」(Usage) 中確認確切層級。
• 若創建回應包含 task_id、status: "pending" 或 poll_url，代表您必須輪詢 GET /v1/tasks/{id}，直到狀態變為 completed 或 failed。
• 即使任務失敗，狀態讀取仍會返回 HTTP 200。請根據任務的 status 欄位進行分支判斷，而非 HTTP 代碼。
• 最終費用顯示在「使用量」(Usage) 與 billing_transaction_id 中，而非複製的價格表中。

Nano Banana API 模型、定價單位與用途

當我們將本指南的早期草稿與當前文件進行比較時，發現了三個問題：它列出了沒有價格的模型；它透過聊天完成 (chat completions) 發送 Nano Banana 編輯請求；它使用圖像指南未使用的篩選器來查詢目錄。下表修正了第一個問題，後續章節則修正了另外兩個。

模型 ID	最佳用途	定價單位	TokenLab 價格 (USD)	來源，觀察日期
nano-banana-2	文字轉圖像與圖像轉圖像，支援 aspect_ratio 與 resolution (1k, 2k, 4k)。發佈於 2026-02-26。	per_image	每次請求 $0.0335。區間 $0.0225 至 $0.0755。	即時模型 API, 2026-10-03
nano-banana-2-lite	最便宜的文字轉圖像與圖像轉圖像。我們看到的價格條目涵蓋 1k 層級。	per_image	每次請求 $0.0168。最低與最高皆為 $0.0168。	即時模型 API, 2026-10-03
nano-banana-pro	文字轉圖像、圖像轉圖像與圖像編輯，支援 aspect_ratio 與 resolution。	per_image	每次請求 $0.067。區間 $0.067 至 $0.12。	即時模型 API, 2026-10-03
nano-banana	僅支援 aspect_ratio 的文字轉圖像。無公開的 resolution 選擇。	無相關證據	請查看模型頁面或定價端點	目錄, 2026-10-02; 創建圖像文件, 2026-10-03

上述所有價格均帶有 is_lock_price: true，並於 2026-10-02T16:53:30.068Z 更新。在選擇模型前，有三個細節需要注意：

• 解析度層級會影響價格。 即時 API 顯示 nano-banana-2 與 nano-banana-pro 的價格區間，但我們的證據並未將每個層級對應到特定解析度。請勿假設 1k 就是基礎價格，請閱讀您所選模型的定價條目。
• 文字輸出有其專屬的 token 價格。 nano-banana-2 與 nano-banana-pro 皆帶有 native-gemini-text-output 條目。當 outputModality 為 text 時適用。對於 nano-banana-2，其列出輸入 0.25 與輸出 1.5；對於 nano-banana-pro，其列出輸入 1 與輸出 6。單位為 per_token。在進行預算規劃前，請先在 GET /v1/models/:model/pricing 確認比例。
• Lite 版本未列出接受的請求格式。 nano-banana-2-lite 的即時記錄顯示為「未列出」。在針對其進行開發前，請先閱讀其詳細資訊。

若要進行粗略預算，我們將基礎價格乘以數量。這些是基於基礎價格的估算值，而非報價：

• 在 nano-banana-2-lite 上生成 100 張圖像：100 × $0.0168 = $1.68。
• 在 nano-banana-2 上生成 100 張圖像：100 × $0.0335 = $3.35。
• 在 nano-banana-pro 上生成 100 張圖像：100 × $0.067 = $6.70。

更高的解析度層級會增加這些數字。

若要自行列出當前的圖像模型，請呼叫圖像生成指南中使用的端點。早期草稿使用了 category=image，但該指南並未記錄此參數。

curl "https://api.tokenlab.sh/v1/models?recommended_for=image" \
  -H "Authorization: Bearer sk-your-api-key"

關於單一模型的運作、價格與生命週期，請使用獲取模型 (Get a Model)。您也可以瀏覽 TokenLab 模型目錄。

使用 Nano Banana API 發送文字轉圖像請求

在 TokenLab 儀表板中建立 API 金鑰並匯出：

export TOKENLAB_API_KEY="your-tokenlab-api-key"

請務必發送 model。創建圖像參考文件指出圖像 API 不會自動選擇預設模型。缺少模型參數會返回 400 錯誤，並顯示 param: "model"。

此請求僅使用 Google 圖像系列文件中列出的欄位。我們將 resolution 保持為 1k，因為 nano-banana-2 支援 1k、2k 與 4k。

curl -X POST "https://api.tokenlab.sh/v1/images/generations" \
  --max-time 120 \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "A minimalist ceramic vase on a natural wooden table, studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "1k",
    "response_format": "url"
  }'

--max-time 120 旗標符合文件要求。文件指出高解析度請求可能需要一分鐘或更長時間，因此請將客戶端超時時間設定為至少 120 秒。文件提到 size 是 Google 圖像系列的相容性別名，但建議直接使用 aspect_ratio。

同步成功會直接返回完成的圖像。下方的佔位符僅展示記錄的格式：

{
  "created": 1700000000,
  "data": [
    { "url": "https://example.com/generated-image.png" }
  ]
}

請依照此順序讀取：

1. 如果主體包含 task_id、status: "pending" 或 poll_url，代表您得到的是任務而非圖像。請前往輪詢章節。
2. 否則，請讀取 data[0].url。若使用 response_format: "b64_json"，請改為讀取 data[0].b64_json。
3. created 為 Unix 時間戳。revised_prompt 僅在模型返回時出現，請勿強制要求。
4. 儲存圖像 URL、您自己的工作 ID、模型以及回應標頭中的 request_id。

生成的圖像 URL 可能會作為媒體副本保留 30 天。請檢查每個項目的 media_retention.items 以確認狀態與 expires_at。擱置或失敗的副本不保證保留，若需長期使用，請將檔案複製到您自己的儲存空間。資料保留指南有詳細說明。

使用參考 URL 編輯圖像

假設目錄團隊希望在乾淨的攝影棚背景下拍攝相同的產品照片。誘人的做法是使用 /v1/images/edits，但文件排除了此選項。Nano Banana 參考圖像請求需透過 /v1/images/generations 並使用 operation: "image-to-image"。/v1/images/edits 並非正確的路徑。

此請求來自圖像生成指南，模型為 nano-banana-2：

curl https://api.tokenlab.sh/v1/images/generations \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "operation": "image-to-image",
    "prompt": "Keep the product shape, change the background to a bright studio setup",
    "image_urls": ["https://example.com/input/product.png"],
    "aspect_ratio": "1:1"
  }'

我們遵循以下規則：

• 發送確切的文件參考欄位。 在 JSON 中使用 image_url、image_urls 或 reference_image_urls。請勿發送頂層的 images[] 或 file_id，這些屬於編輯流程，在此端點會被拒絕。
• 使用公開 URL。 必須是 http 或 https，不得包含嵌入式憑證、片段或私有網路主機。避免使用可能在處理開始前過期的簽名 URL。
• 針對私有來源使用 multipart。 對於私有或受標頭保護的來源，文件提供了 multipart image 檔案選項。
• 將 resolution 與模型匹配。 文件指出 nano-banana-pro 可能包含此欄位，而 nano-banana-edit 應省略。文件也將 nano-banana-edit 命名為參考圖像模型，但該 ID 並未出現在我們 2026-10-02 抓取的目錄中。在使用前，請務必對照 /v1/models 驗證任何 ID。

原始文章的聊天完成編輯範例已移除。即時記錄列出 gemini_generate_content 為 nano-banana-2 與 nano-banana-pro 可接受的格式。我們的證據並未記錄聊天完成的圖像編輯路徑。

基於遮罩的修復 (inpainting) 與參數（如 strength）在我們的證據中未針對 Nano Banana 進行記錄。在發送前，請先檢查 GET /v1/models/{model}。

圖像請求何時變為任務以及如何輪詢

圖像創建調用可能是同步或非同步，回應會告知您結果。非同步工作指南列出了觸發欄位：task_id、status: "pending" 或 poll_url。如果出現任何一個，代表 data[] 陣列為空，且工作仍在執行中。

我們的證據僅針對 gpt-image-2 與官方 FLUX/BFL 圖像模型記錄了 async: true 請求旗標。它並未針對 Nano Banana ID 進行記錄。請勿將其加入 Nano Banana 請求中。若收到任務回應，請處理該回應；若需要非同步行為，請檢查模型詳細資訊。

想像一下瀏覽器重新整理在緩慢的回應後重新發送了創建調用，您現在需要為兩次生成付費。文件指出大多數重複生成都來自此類重試。請依照此順序：

1. 立即儲存 ID。 儲存 id 或 task_id、poll_url、模型、端點以及您自己的工作 ID。id 與 task_id 為相同值。
2. 輪詢 URL。 出現時使用 poll_url。否則請呼叫固定路由：

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

1. 每 5–10 秒輪詢一次。 指南指出這對於長時間的媒體工作通常足夠。
2. 了解狀態。 狀態包括 pending、processing、completed 與 failed。已取消的任務會顯示 failed 並帶有 cancelled: true。
3. 在終止狀態停止。 當狀態為 completed 時，讀取 data[].url。非同步圖像結果僅為 URL，絕非 b64_json。當狀態為 failed 時，讀取 error 與 error_details。
4. 安全處理超時。 如果創建調用在看到回應前超時，請檢查 request_id 並在重試前尋找任務。如果您儲存了任務 ID，請恢復輪詢。如果狀態輪詢失敗，請使用退避機制 (backoff) 重試該輪詢，不要重新創建。

即使任務失敗，狀態讀取仍會返回 HTTP 200。失敗的任務可能包含 error_details，其中包含 status、type、code、message、param 與 retryable。例如，error_details.status: 400 且 param: "size" 意味著請求需要修正，並不代表輪詢本身失敗。重試失敗的生成會創建新任務，並可能產生新費用。

預期錯誤與處理方式

請依據 HTTP 狀態與 code 處理錯誤，絕不要依據 message。錯誤處理指南指出訊息可能會在未經通知的情況下變更。Chat Completions 與 Responses 使用 OpenAI 風格的 error 物件，而 Gemini 與 Anthropic 格式則保留其各自的形狀。請勿在所有 TokenLab API 之間共用同一個解析器。

狀態 / 代碼	可能原因	處理方式
400, param: "model"	未指定模型	發送 model。使用 /v1/models?recommended_for=image 列出 ID。
400 unsupported field, 或 unsupported_parameter	模型未記錄的欄位，例如在不支援的模型上使用 resolution	移除該欄位或切換模型。請勿重複發送未變更的請求。
400 參考圖像錯誤	端點錯誤，或 URL 私有/過期	使用 /v1/images/generations 並帶有 image_urls。使用公開且穩定的 URL。
401 invalid_api_key 或 expired_api_key	金鑰遺失、撤銷或過期	更換金鑰。
402 insufficient_balance 或 quota_exceeded	餘額不足，或金鑰達到自身限制	儲值、提高金鑰限制或選擇價格較低的模型。
403 model_not_allowed	金鑰無法使用該模型	更新金鑰的模型列表。
404 model_not_found	未知或不可用的 ID	讀取 /v1/models 並使用當前 ID。
413 payload_too_large	請求或檔案過大	減少輸入內容。
429 rate_limit_exceeded	視窗內請求過多	等待 Retry-After 後重試。
500–504, all_channels_failed	服務或供應問題	僅在 retryable 為 true 時重試。遵守 retry_after 並限制嘗試次數。

503 all_channels_failed 不一定代表服務中斷。如果 retryable 為 false 且缺少 retry_after，代表所選的交付層級沒有供應量。重複請求無濟於事，請先檢查 GET /v1/models。

任務輪詢有其自身的失敗情況：

• 404 async_task_not_found：任務已過期或消失。檢查儲存的 task_id 與 poll_url。
• 403 task_not_owned：任務屬於另一個工作區。檢查 API 金鑰屬於哪個工作區。
• 已完成但沒有媒體 URL 的任務：視為失敗。保留 ID 並聯繫支援團隊。

聯繫支援團隊時，請發送 request_id、task_id、billing_transaction_id（若有）、端點、模型、時間與欄位名稱。絕不要發送金鑰、私有媒體或簽名 URL。

圖像請求的費用如何決定

所有三個有定價的 Nano Banana ID 皆使用 per_image 單位，因此主要費用為模型的 per_request 價格。帳單指南補充了相關規則：

• 一次結果，一次收費。 每個完成的請求都會針對產生該結果的交付選項收費一次。TokenLab Verified 使用 TokenLab 公開價格；Official 使用官方價格層級；Auto 會先嘗試 Verified，再嘗試 Official。
• 層級設定最終數字。 即時價格區間（nano-banana-2 為 $0.0225 至 $0.0755，nano-banana-pro 為 $0.067 至 $0.12）顯示單一固定價格無法涵蓋所有請求。解析度層級可能是主要驅動因素，請在模型的定價條目中確認。
• 任務優先預留。 非同步任務在被接受時可能會預留其估計成本。已完成的任務收費一次，失敗的任務會釋放或退還預留金額。帳單指南指出失敗的任務不收費。
• 破折號不代表免費。 在模型頁面上，TokenLab 價格欄中的破折號表示目前沒有 Verified 報價。

若要確認費用，請使用以下位置：

1. GET /v1/models/:model/pricing 或 定價 API 查詢當前價格。
2. 控制台，會在您確認付費生成前顯示最高估計值。
3. 使用量 (Usage) 查詢各模型的最終費用。
4. 回應或任務中的 billing_transaction_id，以及 X-Billing-Transaction-ID 標頭。串流與某些原生格式可能僅在標頭中公開此 ID。

如果任務完成後，「使用量」未顯示最終費用或釋放金額，請將 Request ID 與 task ID 發送至 support@tokenlab.sh。請勿將本文中的價格複製到您的程式碼中。帳單指南建議在您的應用程式需要顯示或比較成本時，讀取當前價格。

常見問題

我應該為圖像轉圖像請求發送哪個 Nano Banana 模型 ID？

即時記錄列出了 nano-banana-2、nano-banana-2-lite 與 nano-banana-pro 的 image-to-image 功能。文件也提到了 nano-banana-edit，但它並未出現在我們 2026-10-02 抓取的目錄中。請發送帶有 operation: "image-to-image" 與 image_urls 的 ID 至 /v1/images/generations。由於我們的證據中沒有品質比較，請在您自己的圖像上進行小規模測試。

為什麼我的圖像請求返回了 task_id 而不是圖像？

創建調用以非同步任務執行。請在回應中尋找 task_id、status: "pending" 或 poll_url。儲存這些欄位，然後每 5–10 秒輪詢 poll_url 或 GET /v1/tasks/{id}，直到狀態變為 completed 或 failed。等待期間請勿發送第二次創建請求。

我可以從 Nano Banana 模型獲得 base64 輸出嗎？

response_format 欄位接受 url 或 b64_json，同步請求可以返回 data[].b64_json。非同步圖像結果僅為 URL，無論您要求何種格式。請檢查所選模型的詳細資訊以確認其是否接受 b64_json，因為欄位會因模型而異。

失敗的圖像任務會收費嗎？

帳單指南指出失敗的任務不收費，任何預留金額都會被釋放或退還。重試失敗的生成會創建新任務，並可能產生新費用。請使用 billing_transaction_id 與 task_id 在「使用量」中確認結果。

在 TokenLab 儀表板中建立金鑰，使用 nano-banana-2-lite 發送上述文字轉圖像請求，並在「使用量」中檢查費用。