> ## Documentation Index
> Fetch the complete documentation index at: https://mixroute.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Gemini 原生（圖片）
> Gemini 原生圖片生成、編輯欄位與模型限制。
使用 Gemini 原生 Content 片段和 generationConfig 設定生成、編輯圖片。
`POST https://api.mixroute.ai/v1/models/{model}:generateContent`
## 支援模型
| 模型 ID | 能力與限制 |
| - | - |
| `gemini-nano-banana-2.1` | Nano Banana 2.1；1K/2K/4K 輸出；MINIMAL/MEDIUM/HIGH 思考，預設 MEDIUM。 |
| `gemini-3.1-flash-image` | Nano Banana 2，支援 512、1K、2K、4K 輸出及 MINIMAL/HIGH 思考等級。 |
| `gemini-3.1-flash-image-preview` | Nano Banana 2，支援 512、1K、2K、4K 輸出及 MINIMAL/HIGH 思考等級。 |
| `gemini-3-pro-image` | Nano Banana Pro，支援 1K、2K、4K 輸出及圖文推理。 |
| `gemini-3-pro-image-preview` | Nano Banana Pro，支援 1K、2K、4K 輸出及圖文推理。 |
| `gemini-3.1-flash-lite-image` | Nano Banana 2 Lite，僅 1K 輸出，不支援 Google Search 搜尋增強。 |
| `gemini-2.5-flash-image` | 初代 Nano Banana，約 1K 輸出，不傳 imageSize。 |
## 請求參數
| 欄位 | 型別 | 必填 | 說明 |
| - | - | - | - |
| `model (URL path)` | string | 是 | 端點路徑中的模型 ID，不額外放進 JSON 請求體。 |
| `contents` | object\[] | 是 | 包含文本和可選圖片輸入的對話輪次。 |
| `contents[].role` | string | 否 | `user` 或 `model`，保留上一輪模型輸出時使用 model 角色。 |
| `contents[].parts` | object\[] | 是 | 內容片段陣列，編輯時可組合文本指令和圖片片段。 |
| `contents[].parts[].text` | string | 按場景 | 文本提示詞或編輯指令。 |
| `contents[].parts[].inlineData` | object | 按場景 | 內聯圖片資料，包含 mimeType 和原始 Base64 data；data 不包含 data-URI 字首。 |
| `contents[].parts[].inlineData.mimeType` | string | 按場景 | 圖片 MIME 型別，例如 image/png、image/jpeg 或 image/webp。 |
| `contents[].parts[].inlineData.data` | string | 按場景 | 圖片二進位制內容的 Base64 編碼。 |
| `contents[].parts[].fileData` | object | 否 | 包含 fileUri 和 mimeType 的原生檔案引用，須能被當前路由的上游賬號訪問。 |
| `contents[].parts[].thoughtSignature` | string | 否 | 模型返回的不透明簽名；多輪對話回傳模型內容時須原樣保留，不要自行生成或修改。 |
| `systemInstruction` | object | 否 | 原生系統指令 Content 物件，通常使用 parts\[].text。 |
| `generationConfig` | object | 否 | 原生生成設定。 |
| `generationConfig.responseModalities` | string\[] | 否 | 請求圖片輸出時包含 IMAGE，可同時包含 TEXT，例如 \["TEXT", "IMAGE"]。 |
| `generationConfig.imageConfig.aspectRatio` | string | 否 | 輸出寬高比；省略時由模型根據輸入選擇，不保證正方形。可用比例見下方。 |
| `generationConfig.imageConfig.imageSize` | string | 否 | 預設 1K。Nano Banana 2.1 和 Pro：1K/2K/4K；Nano Banana 2（3.1 Flash Image）：512/1K/2K/4K；Lite 僅 1K；2.5 Flash Image 不傳此欄位。 |
| `generationConfig.thinkingConfig.thinkingLevel` | string | 否 | Nano Banana 2.1：MINIMAL、MEDIUM（預設）、HIGH；3.1 Flash Image 和 Lite：MINIMAL（預設）或 HIGH，不跨型號套用。 |
| `generationConfig.thinkingConfig.includeThoughts` | boolean | 否 | 是否在響應中包含模型可提供的思考摘要或片段；讀取最終圖片時跳過 thought=true 的片段。 |
| `generationConfig.maxOutputTokens` | integer | 否 | 文本和影像共用的輸出預算，過低可能無法返回完整圖片，須遵守模型上限。 |
| `tools` | object\[] | 否 | 原生工具。路由允許時，Nano Banana 2.1、3.1 Flash Image、Pro 可使用 Google Search 搜尋增強；Lite 和 2.5 Flash Image 不支援此流程。 |
| `safetySettings` | object\[] | 否 | 包含 category 和 threshold 的原生安全設定，受模型及賬號策略約束，同一類別不要重複配置。 |
## 模型限制
Nano Banana 2.1 使用相同的原生 Content/Part 請求結構，通過 `generationConfig.imageConfig` 設定圖片輸出，不增加 metadata 或 asset 包裝。輸出檔位為 1K、2K、4K，不使用 512；不傳入不支援的 temperature、topP、topK、seed、logprobs 欄位。模型限制見 [Nano Banana 2.1](/docs/zh-hant/model-api/google/gemini-nano-banana-2.1)。
`1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`
Nano Banana 2.1 和 Gemini 3.1 Flash Image 另支援 1:4、4:1、1:8、8:1。僅使用當前模型支援的尺寸與比例。Gemini 3 影像模型最多支援 14 張參考圖，主體數量限制因模型而異，Lite 面向輕量流程。此介面不通過 OpenAI 的 n 或 size 欄位控制圖片。
## 呼叫示例
將 MixRoute Key 設定到環境變數 `MIXROUTE_API_KEY`，通過 `Authorization: Bearer ...` 認證。編輯圖片前，將素材佔位值替換為可訪問的圖片或本地檔案。
```bash theme={null}
curl --request POST "https://api.mixroute.ai/v1/models/gemini-nano-banana-2.1:generateContent" \
--header "Authorization: Bearer $MIXROUTE_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"contents": [
{
"role": "user",
"parts": [
{
"text": "A clean product photograph of a red ceramic mug on a white background."
}
]
}
],
"generationConfig": {
"responseModalities": [
"TEXT",
"IMAGE"
],
"imageConfig": {
"aspectRatio": "1:1",
"imageSize": "1K"
}
}
}'
```
### Python
```python theme={null}
import json
import os
import requests
payload = json.loads(r'''
{
"contents": [
{
"role": "user",
"parts": [
{
"text": "A clean product photograph of a red ceramic mug on a white background."
}
]
}
],
"generationConfig": {
"responseModalities": [
"TEXT",
"IMAGE"
],
"imageConfig": {
"aspectRatio": "1:1",
"imageSize": "1K"
}
}
}
''')
response = requests.post(
"https://api.mixroute.ai/v1/models/gemini-nano-banana-2.1:generateContent",
headers={"Authorization": "Bearer " + os.environ["MIXROUTE_API_KEY"]},
json=payload,
timeout=180,
)
response.raise_for_status()
result = response.json()
import base64
from pathlib import Path
image_index = 0
for candidate in result.get("candidates", []):
for part in candidate.get("content", {}).get("parts", []):
if part.get("thought"):
continue
inline = part.get("inlineData")
if inline and inline.get("data"):
extension = {"image/png": "png", "image/jpeg": "jpg", "image/webp": "webp"}.get(inline.get("mimeType"), "bin")
Path(f"image_{image_index}.{extension}").write_bytes(base64.b64decode(inline["data"]))
image_index += 1
elif "text" in part:
print(part["text"])
```
## 圖片編輯與多輪對話
編輯時，在使用者輪次中同時提供 inlineData 圖片片段與文本指令。繼續編輯時，將上一輪完整的 candidate.content 物件追加到 contents，再追加新使用者輪次，以保留原生圖片資料和思考簽名，不要只保留模型的文本。
```json theme={null}
{
"contents": [
{
"role": "user",
"parts": [
{
"text": "Make the mug blue while preserving its shape, lighting, and background."
},
{
"inlineData": {
"mimeType": "image/png",
"data": "BASE64_IMAGE_DATA"
}
}
]
}
],
"generationConfig": {
"responseModalities": [
"TEXT",
"IMAGE"
],
"imageConfig": {
"aspectRatio": "1:1",
"imageSize": "1K"
}
}
}
```
## 響應
從 candidates\[].content.parts\[] 讀取文本和圖片。圖片通常使用 inlineData 中的 mimeType 與 Base64 data，多輪複用模型內容時保留 thoughtSignature。沒有圖片時檢查 promptFeedback 與 finishReason；usageMetadata 是用量統計，不是圖片生成參數。
[Gemini 圖片流式響應](/docs/zh-hant/api-reference/endpoint/nano-banana-stream)
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.