Nano Banana 錯誤排查

參數取值見 Nano Banana 文生圖與尺寸。

先依現象查找

400 Request contains an invalid argument

{
  "error": {
    "code": 400,
    "message": "Request contains an invalid argument.",
    "status": "INVALID_ARGUMENT"
  }
}

此錯誤不會指明具體參數。實測以下情況皆會回傳此錯誤：

排查方式：先移除 imageConfig 重試；若能正常生成，表示問題出在比例或解析度，再逐項加回以找出原因。

比例或解析度不符

請先檢查輸出圖片的實際寬高，再對照下表排查：

正確寫法：

{
  "contents": [{ "parts": [{ "text": "..." }] }],
  "generationConfig": {
    "responseModalities": ["IMAGE"],
    "imageConfig": { "aspectRatio": "9:16", "imageSize": "2K" }
  }
}

imageConfig / image_config、aspectRatio / aspect_ratio 兩種寫法皆可識別，實測 image_config: { aspect_ratio: "9:16" } 正確輸出 768×1376。

回應中沒有圖片

在 Cherry Studio、LobeHub 等用戶端中使用時，請將其新增為圖像生成模型，而非聊天模型。

410 model_deprecated

{
  "error": {
    "message": "Model 'google/gemini-3-pro-image-preview' is deprecated and no longer accepts requests; please switch to an active model",
    "type": "model_deprecated",
    "code": 410
  }
}

以 -preview 結尾的舊 ID 已下線，請改用正式版 ID：

原生介面路徑中的模型 ID 可帶 google/ 前綴，也可省略，實測皆可正常呼叫。

改圖結果與原圖無關

確認參考圖已被讀取：原生介面查看 usageMetadata.promptTokensDetails 中是否包含 IMAGE 項；OpenAI 相容介面查看 usage.input_tokens_details.image_tokens。實測一張 1024×1024 的參考圖計 1,120 個 token。

安全攔截

請求被安全政策攔截時，回應中不含圖片，原因記錄在 finishReason 或 promptFeedback.blockReason 中。各取值的含義（依據 Google 官方定義）：

程式碼中不應假定回應必定包含圖片：應先檢查 candidates 是否存在、finishReason 是否為 STOP，再讀取 inlineData。各欄位定義見 Gemini API · FinishReason 。

逾時、504、524

介面為同步呼叫，實測 1K 約 5 至 20 秒，4K 約 30 秒，尖峰時段耗時更長。常見的 60 秒預設逾時無法涵蓋。

• 用戶端逾時設為 300 秒以上。
• 檢查 Nginx、Vercel、Cloudflare 等中間代理的逾時設定，其預設值通常僅 60 至 100 秒。
• 4K 的 PNG 約 16 MB，回應主體超過 20 MB，請確認代理不會截斷大型回應。

用戶端提前中斷連線時，請求仍會計費。

其他錯誤

聯絡技術支援時，請提供回應中的 request_id 及完整錯誤訊息。

常見問題