Nano Banana 2（Gemini 3.1 Flash Image）

Nano Banana 2 是 Google 的 Gemini 3.1 Flash Image 模型。傳送 Google 的 generateContent 請求體並附上 model 欄位，儲存回傳的任務 ID，然後查詢該任務以取得生成完成的影像。參考圖以 fileData URL 的形式放在 contents 中。

模型 ID

兩個 ID 接受相同的參數。目前價格見模型頁。

快速範例

curl https://api.seedrouter.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image",
    "contents": [{"parts": [{"text": "A ceramic teapot on a linen tablecloth, soft window light"}]}],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {"aspectRatio": "16:9", "imageSize": "2K"}
    }
  }'

端點

POST https://api.seedrouter.ai/v1/images/generations

請求體就是 Google 的 generateContent 請求，只多了一個 model 欄位，因為本端點的路徑中不包含模型名。回應回傳的是任務 ID，而不是生成完成的影像。請把 API Key 儲存在服務端程式碼中。不支援直接呼叫 /v1beta/models/...:generateContent，請使用本端點。

參數

安全類別：HARM_CATEGORY_HARASSMENT、HARM_CATEGORY_HATE_SPEECH、HARM_CATEGORY_SEXUALLY_EXPLICIT、HARM_CATEGORY_DANGEROUS_CONTENT。閾值：BLOCK_NONE、BLOCK_ONLY_HIGH、BLOCK_MEDIUM_AND_ABOVE、BLOCK_LOW_AND_ABOVE、OFF。

未知欄位會被拒絕。暫不支援：Google Search grounding（tools）和快取內容；此模型的文件中沒有 thinkingLevel。不接受 inlineData，請以 fileData URL 傳入媒體。responseFormat.image.delivery 只接受 INLINE：生成完成的影像始終以託管 URL 回傳。

輸出尺寸

其他寬高比的 token 數相同；例如 1K 下的 16:9 為 1376×768。

模式

沒有單獨的模式參數，也沒有單獨的編輯端點。

要繼續一段對話，請依序用上一個任務的 output.parts 重建 model 輪次：文字 part 寫成 {"text": ..., "thoughtSignature": ...}，影像 part 寫成 {"fileData": {"mimeType": "image/<output_format>", "fileUri": <data[image].url>}, "thoughtSignature": ...}。每個 thoughtSignature 都要原樣保留：它是我們為你儲存的簽章的 URL（一張 4K 影像的簽章有好幾 MB），我們會在請求送達模型之前將它還原。只接受你自己任務結果中的簽章。

用參考圖編輯

curl https://api.seedrouter.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image",
    "contents": [{
      "role": "user",
      "parts": [
        {"text": "Turn this photo into a watercolor painting. Keep the composition."},
        {"fileData": {"mimeType": "image/jpeg", "fileUri": "https://example.com/photo.jpg"}}
      ]
    }]
  }'

請把範例 URL 替換成你自己的、可訪問的影像。

媒體輸入

本 API 只接受 URL 引用。不接受 base64 inlineData、data: URL 和 multipart 上傳。Playground 會先把所選檔案上傳到儲存，再提交其 URL。

引用必須是公開可訪問的 HTTP(S) URL，單個檔案小於 50 MB，總計不超過 100 MB：影像（image/png、image/jpeg、image/webp、image/heic、image/heif）、影片（video/mp4、video/mpeg、video/mov、video/avi、video/x-flv、video/mpg、video/webm、video/wmv、video/3gpp）或 PDF 文件（application/pdf）。mimeType 必須與檔案一致。URL 在處理過程中才會被拉取；影像無法訪問會導致任務失敗，失敗的任務不計費。

計費維度

目前費率請檢視模型定價部分。gemini-3.1-flash-image 每交付一張圖收一個固定價，與尺寸和提示詞無關。gemini-3.1-flash-image-official 按用量計費：輸入 token（文字和參考圖）、文字與思考輸出 token、影像輸出 token，各按各自的費率。影像尺寸是主要因素，見上表。

最終扣費請在帳號的用量記錄中檢視。失敗的任務不計費。

輸出結構

提交後回傳一個任務引用：

{
  "id": "task_...",
  "model": "gemini-3.1-flash-image",
  "status": "processing",
  "created_at": 1790310979
}

輪詢任務

curl https://api.seedrouter.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY"

每隔幾秒輪詢一次，直到 status 變為 completed 或 failed。輪詢過程中出現網路超時，並不意味著生成失敗：請保留任務 ID 並繼續查詢。不要為了檢視進度而再建立一個任務。

完整輪詢範例

請在上面的 Python 提交範例之後執行這段程式碼。

import time

deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    result = requests.get(
        f"https://api.seedrouter.ai/v1/tasks/{task_id}",
        headers={"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"},
        timeout=30,
    )
    result.raise_for_status()
    task = result.json()
    if task["status"] == "completed":
        for image in task["output"]["data"]:
            print(image["url"])
        break
    if task["status"] == "failed":
        raise RuntimeError(task["error"]["message"])
    time.sleep(3)
else:
    raise TimeoutError(f"Still waiting. Resume polling task {task_id}.")

已完成的任務

{
  "id": "task_...",
  "model": "gemini-3.1-flash-image",
  "status": "completed",
  "created_at": 1790310979,
  "finished_at": 1790311001,
  "output": {
    "created": 1790310999,
    "data": [{"url": "https://static.seedrouter.ai/media/tasks/task_example/0.jpg"}],
    "output_format": "jpeg",
    "usage": {
      "input_tokens": 27,
      "output_tokens": 1525,
      "total_tokens": 1552,
      "output_tokens_details": {"image_tokens": 1120, "text_tokens": 405, "reasoning_tokens": 0}
    }
  }
}

不支援串流輸出（streamGenerateContent）；結果透過任務交付。

錯誤

在任務建立之前被拒絕的請求，會回傳 HTTP 錯誤狀態碼和一個 error 物件。受理之後才失敗的任務，在查詢時回傳 HTTP 200，並帶有 status: "failed" 和一個 error 物件。影像被模型的安全過濾器攔截時以 content_policy_violation 失敗；回應中沒有影像時以 no_output 失敗。

錯誤碼、HTTP 狀態碼和重試建議請參見公共錯誤目錄。

{
  "id": "task_...",
  "status": "failed",
  "error": {
    "code": 60001,
    "message": "The request was rejected by the content policy. Please revise the prompt or input images."
  }
}

如果提交本身超時，請先檢查你的任務歷史再重新提交：第一次請求有可能已經被受理。

實用建議

• 用完整的句子描述主體、場景、光線和風格。
• 做編輯時，既要說明要改什麼，也要說明哪些必須保持不變。
• 草稿用 512 或 1K，最終素材用 2K 或 4K。
• 需要長期儲存時，請把回傳的影像儲存到你自己的儲存中。

相關內容

• Nano Banana 2 Playground 與定價
• 下載 OpenAPI
• 可複製的 Markdown