> ## 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 原生图片生成、编辑字段与模型限制。

使用 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](/zh-hans/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 图片流式响应](/zh-hans/api-reference/endpoint/nano-banana-stream)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.