Nano Banana（Gemini 圖像模型）

通用資訊

• Base URL：https://api.routeapi.ai
• 認證：Authorization: Bearer $ROUTEAPI_KEY，使用 sk- 開頭的 API Key（在控制台 API Keys 頁面建立）。rat_ 開頭的管理金鑰不能呼叫模型。
• 錯誤格式：{"error": {"message": "...", "type": "...", "code": "..."}}，狀態碼含義見常見錯誤。

目前在售的 Gemini 圖像模型：gemini-3.1-flash-image-preview、gemini-3-pro-image-preview 和 gemini-3.1-flash-lite-image。它們是由 Gemini 渠道提供的圖像生成模型，有兩條呼叫路徑（每個模型的實際清單請在模型中查看 supported_endpoint_types）：

路徑	端點	你送出的請求體
OpenAI 圖像格式	POST /v1/images/generations	OpenAI 圖像 JSON，格式見 OpenAI 圖像格式
Gemini 原生	POST /v1beta/models/{model}:generateContent	Gemini 的 contents + generationConfig

客戶端已經使用 Gemini 協議（Google GenAI SDK）、需要完整控制 responseModalities 和 imageConfig 時，走原生路徑；客戶端只支援 OpenAI 圖像介面時，走 /v1/images/generations。

透過 /v1/images/generations 呼叫

請求格式、認證和錯誤回應體與 OpenAI 圖像格式 相同。RouteAPI 會把你的圖像請求轉換成 Gemini 的 generateContent 呼叫。

請求參數

欄位	類型	必填	說明
model	string	是	Gemini 圖像模型 ID，例如 gemini-3.1-flash-image-preview
prompt	string	是	作為 user 輪次裡的單一文字 part 送出
size	string	否	映射為 generationConfig.imageConfig.aspectRatio（見下表）
n	integer	否	大於 1 時送出為 generationConfig.candidateCount；為 1 或省略時不送出
quality、response_format、style、user、watermark	—	否	該路徑不做轉換，Gemini 適配器會忽略這些欄位

responseModalities 由 RouteAPI 自己填入 ["TEXT", "IMAGE"]，透過這個端點時不需要傳。安全設定取自平台級的 Gemini 設定。

尺寸到長寬比

只有以下精確的 size 值會映射為長寬比：

size	aspectRatio
256x256、512x512、1024x1024	1:1
1536x1024	3:2
1024x1536	2:3
1024x1792	9:16
1792x1024	16:9

已經包含 : 的值會作為長寬比原樣傳遞。其他值（例如 2K 或 auto）完全不送出 imageConfig，由上游預設值決定。該路徑不接受像素尺寸——長寬比是唯一的尺寸控制項。

請求範例

curl https://api.routeapi.ai/v1/images/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "prompt": "A nano banana wearing sunglasses, studio product shot",
    "size": "1536x1024"
  }'

回應

回應會被轉換成 OpenAI 圖像物件；只有內嵌圖像 part 會保留，模型回傳的任何文字都會被丟棄。

{
  "created": 1740000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ]
}

該路徑不會產生 URL——一律讀取 data[].b64_json。回應裡沒有圖像 part 時請求以 500 失敗；被 Gemini 攔截時以 400 失敗，攔截原因會記錄在該請求上。

警告

不要用 /v1/images/edits 給 Gemini 圖像模型傳參考圖。它走的是文字對話路徑：只轉換 prompt，image / images / mask 會被忽略，回傳的是內容中帶 Markdown 圖片的 OpenAI 對話補全，而不是圖像物件。需要圖像輸入時請使用下面的原生請求。

使用 generateContent 原生呼叫

POST /v1beta/models/{model}:generateContent
POST /v1beta/models/{model}:streamGenerateContent?alt=sse

範例：

curl https://api.routeapi.ai/v1beta/models/gemini-3-pro-image-preview:generateContent \
  -H "x-goog-api-key: $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      { "role": "user", "parts": [{ "text": "Draw a cat astronaut on the moon" }] }
    ],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "imageConfig": { "aspectRatio": "16:9", "imageSize": "2K" }
    }
  }'

Gemini 認證

在 /v1beta 路徑上，API Key 可以用三種方式之一傳遞：x-goog-api-key: $ROUTEAPI_KEY、查詢參數 ?key=$ROUTEAPI_KEY，或 Authorization: Bearer $ROUTEAPI_KEY。同時存在多個時，?key= 和 x-goog-api-key 會覆蓋 Authorization。

請求欄位

欄位	類型	必填	說明
contents	array	是	Gemini 對話內容，至少一項。角色為 user 和 model
generationConfig.responseModalities	array of string	實際必填	必須包含 IMAGE，否則模型只回傳文字
generationConfig.imageConfig	object	否	圖像選項，原樣傳給 Gemini。aspectRatio 例如 1:1、3:2、16:9；imageSize 例如 1K、2K、4K。可接受的值取決於模型
generationConfig.candidateCount	integer	否	候選數量；並非所有圖像模型都支援
safetySettings	array	否	Gemini 安全設定，原樣轉發
systemInstruction	object	否	系統指令；也接受 snake_case 的 system_instruction

generationConfig 的欄位同時接受 camelCase 和 snake_case 兩種寫法（例如 responseModalities / response_modalities、imageConfig / image_config），兩者都存在時以 snake_case 為準。imageConfig 及其內容不做校驗，原樣傳遞，因此不支援的 imageSize 由 Gemini 報錯，而不是 RouteAPI。

注意

原生請求不會像 OpenAI 路徑那樣被改寫：RouteAPI 不會替你補 responseModalities。漏掉它是最常見的「請求成功回傳文字、沒有圖像」的原因。

圖像輸入

要編輯或引用圖像，在文字旁加一個內嵌圖像 part：

{
  "contents": [
    {
      "role": "user",
      "parts": [
        { "text": "Repaint this photo as a watercolor illustration" },
        {
          "inlineData": {
            "mimeType": "image/png",
            "data": "iVBORw0KGgoAAAANSUhEUgAA..."
          }
        }
      ]
    }
  ],
  "generationConfig": { "responseModalities": ["TEXT", "IMAGE"] }
}

inlineData 攜帶 Base64 圖像位元組，會原樣轉發給 Gemini。已經上傳到 Google 的檔案也可以用原生 fileData.fileUri part，它同樣屬於轉發範圍。如果客戶端使用的是 OpenAI 對話格式，image_url 內容 part 會在伺服器端下載並轉換成內嵌 part 後再送給 Gemini。

串流輸出

串流由查詢參數 ?alt=sse 決定，而不是由 action 名決定：帶上它後上游 action 變為 streamGenerateContent，回應是 Gemini 的 server-sent events 串流。每個分塊都是標準的 candidates[].content.parts 結構。希望圖像增量到達時使用；否則 :generateContent 會一次回傳完整回應體。

回應

原生路徑原樣回傳 Gemini 的回應結構：

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          { "text": "Here is the image." },
          {
            "inlineData": {
              "mimeType": "image/png",
              "data": "iVBORw0KGgoAAAANSUhEUgAA..."
            }
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 12,
    "candidatesTokenCount": 1120,
    "totalTokenCount": 1132
  }
}

圖像從 parts[].inlineData 讀取，通常會伴隨文字 part。Gemini 攔截請求時，promptFeedback.blockReason 會有值，candidates 為空。

計費

Gemini 圖像模型按 token 計費：生成的圖像計為輸出 token，按輸出價格收費；prompt 和參考圖計為輸入 token。目前費率見模型定價與模型詳情頁。

接下來

• OpenAI 圖像格式 — 共用的 /v1/images 請求格式與編輯行為。
• Seedream — 火山引擎 Seedream 的尺寸與編輯語義。
• 模型 — 查找圖像模型並確認 image-generation 支援。
• 模型定價 — 按 token 與按張計費。