> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mixroute.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Gemini 原生（圖片）

> Gemini 原生圖片生成模型，文字生圖與圖生圖

## 簡介

Nano Banana 對應 Google Gemini 原生圖片生成能力，包括 Nano Banana（`gemini-2.5-flash-image`）、Nano Banana 2（`gemini-3.1-flash-image`、`gemini-3.1-flash-image-preview`）與 Nano Banana Pro（`gemini-3-pro-image`）。呼叫 MixRoute 原生介面時，使用端點 `POST /v1/models/<model>:generateContent`，並傳入符合 Gemini 原生結構的 JSON Payload，支援文字生圖、圖生圖及多圖融合等能力。

完整參數與多模型說明請參見 [圖片生成](/cn/api-reference/endpoint/image-generation)。

## 認證

Bearer Token，例如 `Bearer sk-xxxxxxxxxx`

## 支援的模型

| 模型 ID                            | 說明                                         |
| -------------------------------- | ------------------------------------------ |
| `gemini-2.5-flash-image`         | Nano Banana，高性價比文字生圖/圖生圖，輸出為固定 1024px 級尺寸  |
| `gemini-3.1-flash-image`         | Nano Banana 2，卓越畫質與速度平衡，支援 1K、2K、4K 輸出     |
| `gemini-3.1-flash-image-preview` | Nano Banana 2 預覽版，支援圖片生成測試                 |
| `gemini-3-pro-image`             | Nano Banana Pro，更高畫質與極強細節控制，支援 1K、2K、4K 輸出 |

## 基礎範例

<Tabs>
  <Tab title="文字生圖">
    ```bash theme={null}
    curl -X POST "https://api.mixroute.ai/v1/models/gemini-3.1-flash-image:generateContent" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -d '{
        "contents": [
          {
            "role": "user",
            "parts": [
              {
                "text": "一隻可愛的橘色小貓坐在花園裡，陽光明媚，高品質攝影"
              }
            ]
          }
        ],
        "generationConfig": {
          "responseModalities": [
            "TEXT",
            "IMAGE"
          ],
          "imageConfig": {
            "aspectRatio": "16:9",
            "imageSize": "2K"
          }
        }
      }'
    ```
  </Tab>

  <Tab title="圖生圖">
    ```bash theme={null}
    curl -X POST "https://api.mixroute.ai/v1/models/gemini-3.1-flash-image:generateContent" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -d '{
        "contents": [
          {
            "role": "user",
            "parts": [
              {
                "text": "根據這張圖生成一張俯瞰廣州塔的圖片"
              },
              {
                "inlineData": {
                  "mimeType": "image/png",
                  "data": "iVBORw0KGgoAAA..."
                }
              }
            ]
          }
        ],
        "generationConfig": {
          "responseModalities": [
            "TEXT",
            "IMAGE"
          ],
          "imageConfig": {
            "aspectRatio": "16:9",
            "imageSize": "2K"
          }
        }
      }'
    ```
  </Tab>
</Tabs>

## 請求參數

<ParamField path="model" type="string" required>
  Gemini 原生（圖片）模型識別碼，位於 URL 路徑中，如 `gemini-3.1-flash-image` 或 `gemini-3-pro-image`。
</ParamField>

<ParamField body="contents" type="array" required>
  原生對話或圖片內容列表。

  <Expandable title="contents 子欄位">
    <ParamField body="contents[].role" type="string">
      角色識別，通常為 `"user"`。
    </ParamField>

    <ParamField body="contents[].parts" type="array" required>
      內容區塊列表。每個元素可以是文字提示詞（`{"text": "..."}`）或內嵌媒體資料（`{"inlineData": {"mimeType": "...", "data": "<BASE64>"}}`）。

      <Expandable title="parts 子欄位">
        <ParamField body="contents[].parts[].inlineData" type="object">
          內嵌媒體資料物件。

          <Expandable title="inlineData 子欄位">
            <ParamField body="contents[].parts[].inlineData.mimeType" type="string">
              媒體類型的 MIME 格式，如 `"image/png"`、`"image/jpeg"`、`"image/webp"` 等。
            </ParamField>

            <ParamField body="contents[].parts[].inlineData.data" type="string">
              圖片資料的 Base64 編碼字串（不含前綴）。
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="generationConfig" type="object">
  生成設定參數。

  <Expandable title="generationConfig 子欄位">
    <ParamField body="generationConfig.responseModalities" type="array">
      回應模態。如傳入該欄位，需包含 `"IMAGE"`；常用寫法為 `["TEXT", "IMAGE"]`。
    </ParamField>

    <ParamField body="generationConfig.imageConfig" type="object">
      圖片生成設定。

      <Expandable title="imageConfig 子欄位">
        <ParamField body="generationConfig.imageConfig.aspectRatio" type="string">
          輸出圖片的寬高比。`gemini-2.5-flash-image` 與 `gemini-3-pro-image` 支援 `"1:1"`、`"2:3"`、`"3:2"`、`"3:4"`、`"4:3"`、`"4:5"`、`"5:4"`、`"9:16"`、`"16:9"`、`"21:9"`；`gemini-3.1-flash-image` 系列另外支援 `"1:4"`、`"4:1"`、`"1:8"`、`"8:1"`。
        </ParamField>

        <ParamField body="generationConfig.imageConfig.imageSize" type="string">
          輸出解析度或尺寸級別。`gemini-2.5-flash-image` 不使用該欄位，依寬高比返回固定 1024px 級尺寸；`gemini-3.1-flash-image` 系列與 `gemini-3-pro-image` 支援 `"1K"`、`"2K"`、`"4K"`。
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

更多參數與各模型差異請參見 [圖片生成](/cn/api-reference/endpoint/image-generation)。

## 回應格式

介面返回 JSON 格式的回應，圖片以一個或多個 Base64 編碼的 `inlineData` 形式內嵌在 `candidates` 中：

| 欄位                                                 | 類型      | 說明                        |
| -------------------------------------------------- | ------- | ------------------------- |
| `candidates[].content.parts[].inlineData.mimeType` | string  | 圖片 MIME 類型（如 `image/png`） |
| `candidates[].content.parts[].inlineData.data`     | string  | 圖片的 Base64 編碼資料           |
| `candidates[].finishReason`                        | string  | 生成結束原因，如 `"STOP"`         |
| `usageMetadata.promptTokenCount`                   | integer | 輸入 token 數                |
| `usageMetadata.candidatesTokenCount`               | integer | 輸出 token 數（圖片 token）      |
| `modelVersion`                                     | string  | 實際使用的模型版本                 |
| `createTime`                                       | string  | 生成時間（ISO 8601）            |
| `responseId`                                       | string  | 回應唯一識別碼                   |

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.mixroute.ai/v1/models/gemini-3.1-flash-image:generateContent \
    --header 'Authorization: Bearer sk-xxxxxxxxxx' \
    --header 'Content-Type: application/json' \
    --data '{
      "contents": [
        {
          "role": "user",
          "parts": [
            {
              "text": "一隻可愛的橘色小貓坐在花園裡"
            }
          ]
        }
      ],
      "generationConfig": {
        "responseModalities": [
          "TEXT",
          "IMAGE"
        ],
        "imageConfig": {
          "aspectRatio": "16:9",
          "imageSize": "2K"
        }
      }
    }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.mixroute.ai/v1/models/gemini-3.1-flash-image:generateContent"
  headers = {
      "Authorization": "Bearer sk-xxxxxxxxxx",
      "Content-Type": "application/json"
  }
  payload = {
      "contents": [
          {
              "role": "user",
              "parts": [
                  {
                      "text": "一隻可愛的橘色小貓坐在花園裡"
                  }
              ]
          }
      ],
      "generationConfig": {
          "responseModalities": [
              "TEXT",
              "IMAGE"
          ],
          "imageConfig": {
              "aspectRatio": "16:9",
              "imageSize": "2K"
          }
      }
  }
  response = requests.post(url, json=payload, headers=headers)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.mixroute.ai/v1/models/gemini-3.1-flash-image:generateContent', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk-xxxxxxxxxx',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      contents: [
        {
          role: "user",
          parts: [
            {
              text: "一隻可愛的橘色小貓坐在花園裡"
            }
          ]
        }
      ],
      generationConfig: {
        responseModalities: [
          "TEXT",
          "IMAGE"
        ],
        imageConfig: {
          aspectRatio: "16:9",
          imageSize: "2K"
        }
      }
    })
  });
  const data = await response.json();
  console.log(data);
  ```

  ```php PHP theme={null}
  <?php
  $client = new GuzzleHttp\Client();
  $response = $client->post('https://api.mixroute.ai/v1/models/gemini-3.1-flash-image:generateContent', [
      'headers' => [
          'Authorization' => 'Bearer sk-xxxxxxxxxx',
          'Content-Type' => 'application/json',
      ],
      'json' => [
          'contents' => [
              [
                  'role' => 'user',
                  'parts' => [
                      [
                          'text' => '一隻可愛的橘色小貓坐在花園裡'
                      ]
                  ]
              ]
          ],
          'generationConfig' => [
              'responseModalities' => [
                  'TEXT',
                  'IMAGE'
              ],
              'imageConfig' => [
                  'aspectRatio' => '16:9',
                  'imageSize' => '2K'
              ]
          ]
      ]
  ]);
  echo $response->getBody();
  ```

  ```go Go theme={null}
  package main

  import (
      "bytes"
      "encoding/json"
      "net/http"
  )

  func main() {
      payload := map[string]interface{}{
          "contents": []interface{}{
              map[string]interface{}{
                  "role": "user",
                  "parts": []interface{}{
                      map[string]interface{}{
                          "text": "一隻可愛的橘色小貓坐在花園裡",
                      },
                  },
              },
          },
          "generationConfig": map[string]interface{}{
              "responseModalities": []string{
                  "TEXT",
                  "IMAGE",
              },
              "imageConfig": map[string]interface{}{
                  "aspectRatio": "16:9",
                  "imageSize":   "2K",
              },
          },
      }
      body, _ := json.Marshal(payload)
      req, _ := http.NewRequest("POST", "https://api.mixroute.ai/v1/models/gemini-3.1-flash-image:generateContent", bytes.NewBuffer(body))
      req.Header.Set("Authorization", "Bearer sk-xxxxxxxxxx")
      req.Header.Set("Content-Type", "application/json")
      http.DefaultClient.Do(req)
  }
  ```

  ```java Java theme={null}
  import java.net.http.*;
  import java.net.URI;

  HttpClient client = HttpClient.newHttpClient();
  String json = """
      {
          "contents": [
              {
                  "role": "user",
                  "parts": [
                      {
                          "text": "一隻可愛的橘色小貓坐在花園裡"
                      }
                  ]
              }
          ],
          "generationConfig": {
              "responseModalities": [
                  "TEXT",
                  "IMAGE"
              ],
              "imageConfig": {
                  "aspectRatio": "16:9",
                  "imageSize": "2K"
              }
          }
      }
      """;
  HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://api.mixroute.ai/v1/models/gemini-3.1-flash-image:generateContent"))
      .header("Authorization", "Bearer sk-xxxxxxxxxx")
      .header("Content-Type", "application/json")
      .POST(HttpRequest.BodyPublishers.ofString(json))
      .build();
  HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
  System.out.println(response.body());
  ```

  ```ruby Ruby theme={null}
  require 'net/http'
  require 'json'

  uri = URI('https://api.mixroute.ai/v1/models/gemini-3.1-flash-image:generateContent')
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true

  request = Net::HTTP::Post.new(uri)
  request['Authorization'] = 'Bearer sk-xxxxxxxxxx'
  request['Content-Type'] = 'application/json'
  request.body = {
    contents: [
      {
        role: 'user',
        parts: [
          {
            text: '一隻可愛的橘色小貓坐在花園裡'
          }
        ]
      }
    ],
    generationConfig: {
      responseModalities: [
        'TEXT',
        'IMAGE'
      ],
      imageConfig: {
        aspectRatio: '16:9',
        imageSize: '2K'
      }
    }
  }.to_json

  response = http.request(request)
  puts response.body
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "candidates": [
      {
        "content": {
          "role": "model",
          "parts": [
            {
              "inlineData": {
                "mimeType": "image/png",
                "data": "iVBORw0KGgoAAAANSUhEUgAAAAQAAAAECAIA..."
              }
            },
            {
              "inlineData": {
                "mimeType": "image/png",
                "data": "iVBORw0KGgoAAAANSUhEUgAACAAAAAgACAIA..."
              }
            }
          ]
        },
        "finishReason": "STOP"
      }
    ],
    "usageMetadata": {
      "promptTokenCount": 13,
      "candidatesTokenCount": 1680,
      "totalTokenCount": 1693,
      "trafficType": "ON_DEMAND",
      "promptTokensDetails": [
        {
          "modality": "TEXT",
          "tokenCount": 13
        }
      ],
      "candidatesTokensDetails": [
        {
          "modality": "IMAGE",
          "tokenCount": 1680
        }
      ]
    },
    "modelVersion": "gemini-3.1-flash-image",
    "createTime": "2026-06-24T02:41:32.820834Z",
    "responseId": "3EM7auKMMvmTmecP2dTdsAE"
  }
  ```
</ResponseExample>