# Nano Banana 2.1 — Gemini generateContent

> 使用 Gemini 官方模型名调用 Nano Banana 2.1，通过内联 Base64 参考图生成或编辑图片并读取图片响应。

Canonical URL: https://docs.uniall.ai/zh-CN/models/image/nano-series/nano-banana-2-1/gemini-format
Locale: zh-CN

## 概述

使用 `gemini-nano-banana-2.1` 通过 Gemini 请求格式进行文生图，或使用最多 14 张参考图编辑图片。每次同步请求返回一张图片，Base64 数据位于响应的 `inlineData` 部分。

## 接口

```http
POST /v1beta/models/gemini-nano-banana-2.1:generateContent
```

基础地址为 `https://api.uniall.ai`。主要示例使用 Google 官方模型 ID `gemini-nano-banana-2.1`；兼容地址 `/v1beta/models/nano-banana-2.1:generateContent` 也保留可用。

## 鉴权

使用你的 UniAI 用户 API Key：

```http
x-goog-api-key: <UNIAI_API_KEY>
Content-Type: application/json
```

## 请求参数

`contents` 只传一条 `user` 内容，字段名使用 camelCase。

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `contents` | array | 是 | 只能包含一条 user 内容。 |
| `contents[].role` | string | 是 | `user`。 |
| `contents[].parts[].text` | string | 是 | 非空生成或编辑指令。 |
| `contents[].parts[].inlineData` | object | 条件必填 | 编辑参考图，每张图片添加一个 part，最多 14 张。 |
| `contents[].parts[].inlineData.mimeType` | string | 条件必填 | `image/png`、`image/jpeg` 或 `image/webp`。 |
| `contents[].parts[].inlineData.data` | string | 条件必填 | 不带 Data URL 前缀的纯 Base64 图片数据。 |
| `generationConfig.imageConfig.imageSize` | string | 否 | `1K`、`2K` 或 `4K`，默认 `1K`。 |
| `generationConfig.imageConfig.aspectRatio` | string | 否 | 下方 14 种画幅之一；不传时按参考图或生成内容决定。 |
| `generationConfig.thinkingConfig.thinkingLevel` | string | 否 | `MINIMAL`、`MEDIUM` 或 `HIGH`，默认 `MEDIUM`。 |
| `generationConfig.responseModalities` | string[] | 否 | 默认 `["IMAGE"]`，也接受 `["TEXT", "IMAGE"]`。只有实际生成最终文字时才返回文字，不支持仅 `["TEXT"]`。 |
| `generationConfig.candidateCount` | integer | 否 | 只能为 `1`，每次请求返回一张图片。 |

### 分辨率与参考图

支持的画幅：

```markdown
1:1  1:4  1:8  2:3  3:2  3:4  4:1
4:3  4:5  5:4  8:1  9:16  16:9  21:9
```

分辨率是档位，并非固定的长边像素。例如非方形 `1K` 结果可以是 `1376 × 768`。不支持 `0.5K`、`512` 和 `8K`。

编辑需要 1 至 14 张 PNG、JPEG 或 WebP 参考图，按指令描述的顺序放入 `parts`。保留输入顺序及重复项，重复图计入张数限制。`mimeType` 必须与图片实际格式一致，`data` 只放纯 Base64。

## 请求示例

### 文生图

```bash
curl -X POST "https://api.uniall.ai/v1beta/models/gemini-nano-banana-2.1:generateContent" \
  -H "x-goog-api-key: <UNIAI_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {"text": "Create a spring latte poster with a cream background and clear typography"}
        ]
      }
    ],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {"imageSize": "2K", "aspectRatio": "16:9"},
      "thinkingConfig": {"thinkingLevel": "HIGH"},
      "candidateCount": 1
    }
  }'
```

### 图片编辑

发送前，将 `<BASE64_IMAGE_BYTES>` 替换为参考图的纯 Base64 数据。

```bash
curl -X POST "https://api.uniall.ai/v1beta/models/gemini-nano-banana-2.1:generateContent" \
  -H "x-goog-api-key: <UNIAI_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {"text": "Keep the cup shape and color; replace the background with a bright cafe"},
          {
            "inlineData": {
              "mimeType": "image/png",
              "data": "<BASE64_IMAGE_BYTES>"
            }
          }
        ]
      }
    ],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {"imageSize": "2K", "aspectRatio": "4:5"},
      "thinkingConfig": {"thinkingLevel": "MEDIUM"},
      "candidateCount": 1
    }
  }'
```

每增加一张参考图，添加一个 `inlineData` part。继续编辑时，可将上一次输出图片作为下一次独立请求的参考图。

## 响应示例

```json
{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "inlineData": {
              "mimeType": "image/png",
              "data": "<BASE64_IMAGE_BYTES>"
            }
          }
        ]
      },
      "finishReason": "STOP"
    }
  ]
}
```

| 响应字段 | 说明 |
| --- | --- |
| `candidates[].content.parts[].inlineData` | 最终图片。对 `data` 进行 Base64 解码，并按返回的 `mimeType` 保存。 |
| `candidates[].content.parts[].text` | 请求 `["TEXT", "IMAGE"]` 且实际生成最终文字时，可能返回最终文字；不保证必有文字。 |
| `usageMetadata` | 有真实用量元数据时可能返回；读取图片不应依赖此字段。 |

遍历响应部分并查找 `inlineData`，不要假定第一个 part 就是图片。此接口同步返回结果，没有任务 ID 或轮询步骤。客户端超时不能确认生成已停止，应避免自动重新提交请求。

## 能力限制与常见错误

- 搜索尚未开放。不要传入 `tools`、`enable_web_search` 或 `enable_image_search`；即使搜索开关为 `false` 也会拒绝。
- 当前图片接入仅支持单条 user 内容及文字、图片参考，不开放多轮历史、思考签名或摘要、视频/PDF 输入、Files、Interactions 和 Batch API。
- 不支持 `quality`、自定义像素 `size` 或 `custom_size`、遮罩、透明背景、`seed` 或流式输出。
- Nano Banana 2.1 不支持 `/v1/chat/completions` 或 `/v1/images/tasks`。
- 编辑缺少参考图、参考图超过 14 张、在 `inlineData.data` 中包含 Data URL 前缀、不支持的分辨率、仅文字输出或 `candidateCount` 不为 `1`，均属于无效请求。
- 思考档位控制只对新接入的 2.1 开放；`nano-banana-2`、`nano-banana-pro` 和固定分辨率兼容型号未开放此能力。

## 相关页面

- [Nano 系列](/zh-CN/models/image/nano-series)
- [Nano Banana 2.1 — OpenAI Images](./openai-format)
- [其它 Nano 型号的 Gemini generateContent 格式](/zh-CN/models/image/nano-series/gemini-format)