> ## Documentation Index
> Fetch the complete documentation index at: https://quwan-b8010aef.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Nano Banana (Gemini) 图片生成

> 使用 Nano Banana 2.1、Nano Banana 2 和 Pro 进行文生图、参考图编辑及多图合成，包含参数矩阵、图片保存和用量说明

# Nano Banana 图片生成

使用文本生成图片，或提供参考图进行编辑、风格转换和多图合成。平台提供同步图片入口、异步任务入口和 Gemini 原生入口。

## 模型与接口

请求中使用平台模型名：`gemini-nano-banana-2.1`、`nano-banana-2` 或 `nano-banana-pro`。可调用的模型以你的 API Key 查询 `/v1/models` 的结果为准。

| 使用方式 | 方法与路径 | 请求与结果 |
| - | - | - |
| 同步生图和参考图编辑 | `POST /v1/images/generations` | JSON 请求；等待生成完成，返回 `data[].b64_json` |
| 异步生图和参考图编辑 | `POST /v1/images/generations/async` | 相同的图片参数；提交后返回任务 ID，完成后取图片 URL |
| Gemini 原生生成与编辑 | `POST /v1beta/models/{model}:generateContent` | 使用 `contents` 与 `generationConfig`；图片位于 `inlineData` |

参考图编辑同样使用 `/v1/images/generations` 的 `image` 字段。本页的 Gemini 图片入口不支持 `/v1/images/edits` 或 multipart 请求。

本文示例使用 `https://api.tokenops.ai`。使用公司平台入口时，可将地址替换为 `https://model-api.skyengine.com.cn`，并使用该入口对应的 API Key。

## 同步文生图

以下示例使用 Nano Banana 2.1，生成一张 1K 正方形图片。

```bash cURL theme={null}
curl --request POST 'https://api.tokenops.ai/v1/images/generations' \
  --header "Authorization: Bearer $TOKENOPS_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gemini-nano-banana-2.1",
    "prompt": "白色背景上的一根黄色香蕉，柔和自然光，产品摄影，无文字",
    "n": 1,
    "size": "1K",
    "ratio": "1:1",
    "response_format": "b64_json"
  }' --output result.json

# 确认请求成功且 data 中包含图片后保存文件。
jq -r '.data[0].b64_json' result.json | base64 --decode > banana.png
```

```python Python theme={null}
import base64
import os
from pathlib import Path

import requests

base_url = os.getenv("TOKENOPS_BASE_URL", "https://api.tokenops.ai")
response = requests.post(
    f"{base_url}/v1/images/generations",
    headers={"Authorization": f"Bearer {os.environ['TOKENOPS_API_KEY']}"},
    json={
        "model": "gemini-nano-banana-2.1",
        "prompt": "白色背景上的一根黄色香蕉，柔和自然光，产品摄影，无文字",
        "n": 1,
        "size": "1K",
        "ratio": "1:1",
        "response_format": "b64_json",
    },
    timeout=300,
)
response.raise_for_status()
result = response.json()
for index, image in enumerate(result["data"]):
    Path(f"banana-{index}.png").write_bytes(base64.b64decode(image["b64_json"]))
print(result.get("usage", {}))
```

```javascript Node.js theme={null}
import { writeFile } from "node:fs/promises";

const baseURL = process.env.TOKENOPS_BASE_URL || "https://api.tokenops.ai";
const response = await fetch(`${baseURL}/v1/images/generations`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TOKENOPS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "gemini-nano-banana-2.1",
    prompt: "白色背景上的一根黄色香蕉，柔和自然光，产品摄影，无文字",
    n: 1,
    size: "1K",
    ratio: "1:1",
    response_format: "b64_json",
  }),
  signal: AbortSignal.timeout(300_000),
});
if (!response.ok) throw new Error(await response.text());
const result = await response.json();
for (const [index, image] of result.data.entries()) {
  await writeFile(`banana-${index}.png`, Buffer.from(image.b64_json, "base64"));
}
console.log(result.usage);
```

## 参考图编辑与多图合成

`image` 可使用一张图片的字符串，或多张图片的字符串数组。支持公开可访问的 HTTPS URL、`data:image/png;base64,...` 形式的 Data URL，以及图片的裸 base64。使用 Data URL 可以明确图片格式。

```bash 单图编辑 theme={null}
curl --request POST 'https://api.tokenops.ai/v1/images/generations' \
  --header "Authorization: Bearer $TOKENOPS_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gemini-nano-banana-2.1",
    "prompt": "保留参考图中商品的形状和颜色，将背景改为浅蓝色摄影棚，添加自然阴影",
    "image": "https://example.com/product.png",
    "n": 1,
    "size": "2K",
    "ratio": "4:3",
    "response_format": "b64_json"
  }'
```

```bash 多图合成 theme={null}
curl --request POST 'https://api.tokenops.ai/v1/images/generations' \
  --header "Authorization: Bearer $TOKENOPS_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "nano-banana-2",
    "prompt": "将第一张图片中的商品放入第二张图片的场景，保持商品外观，匹配光照与透视",
    "image": [
      "https://example.com/product.png",
      "https://example.com/scene.png"
    ],
    "n": 1,
    "size": "1K",
    "ratio": "16:9",
    "response_format": "b64_json"
  }'
```

将示例 URL 替换为实际图片地址。需要鉴权、已过期或无法由平台访问的链接不适合作为参考图；建议改传 Data URL。编辑时直接在 `prompt` 中描述需要保留和改变的内容，不使用 `mask`。

## 参数矩阵

下表说明同步与异步图片入口的当前参数行为。原生 `generateContent` 使用后文的 Gemini 参数结构。

| 参数 | `gemini-nano-banana-2.1` | `nano-banana-2` | `nano-banana-pro` | 平台行为 |
| - | - | - | - | - |
| `model` | 必填，使用本列名称 | 同左 | 同左 | 不使用拼写变体或自行添加前缀 |
| `prompt` | 必填，非空字符串 | 同左 | 同左 | 文生图与参考图编辑均需提供 |
| `image` | 单图或多图 | 同左 | 同左 | 字符串或字符串数组；URL、Data URL、裸 base64 |
| `n` | `1` | `1` | `1` | 省略时按单次生成处理；大于 1 或负值返回 400 |
| `size` | `1K`、`2K`、`4K` | `512`、`1K`、`2K`、`4K` | `1K`、`2K`、`4K` | `0.5K` 转为 `512`；大小写会规范化；2.1 和 Pro 不使用 `512` |
| `ratio` | 常用比例及超宽比例 | 同左 | 常用比例 | 可用值见下文；省略时不指定比例 |
| `thinking_level` | 显式设置用 `high`；省略使用模型默认强度 | 显式设置用 `high`；低延迟场景省略 | 建议省略 | 当前图片入口不能关闭思考；其他档位说明见下文 |
| `image_search` | 可传 `true` / `false` | 同左 | 同左 | 默认为关闭；开启的是 Google Search 文本搜索接地，不能指定图片搜索模式 |
| `response_format` | 示例统一使用 `b64_json` | 同左 | 同左 | 同步返回 base64；异步结果转存后返回 URL，不能用同步请求的 `url` 值获得图片链接 |
| `stream` | 不支持 | 不支持 | 不支持 | 使用非流式请求；传 `true` 返回 400 |
| `quality`、`background`、`seed`、`mask`、`optimize_prompt_options` | 不支持 | 同左 | 同左 | 不作为 Gemini 图片生成参数使用 |

### 比例与分辨率

常用比例：`1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9`、`21:9`。

Nano Banana 2 和 2.1 还支持 `1:4`、`4:1`、`1:8`、`8:1`。Pro 使用常用比例。

`ratio` 控制画面形状，`size` 控制分辨率档位。例如 `ratio="16:9"` 与 `size="2K"` 可以组合使用。实际像素宽高由模型按比例和档位确定，不能把 `2K` 理解为每条边都等于 2048 像素。

> [!NOTE]
>
> 不要在 Gemini 图片请求中用 `size="1024x1024"` 指定像素。当前平台仅识别分辨率档位，像素尺寸、`auto` 和其他未识别的值会被忽略，由模型选择默认档位。新模型 2.1 不支持 `512`；需要较小图片时请使用 `nano-banana-2`。

### 思考与搜索

当前图片入口显式设置思考强度时，建议使用 `thinking_level="high"`，或省略此参数保留模型默认行为。Nano Banana 2.1 默认使用 `medium`；Nano Banana 2 默认使用 `minimal`。`high` 可能增加生成耗时和思考用量，不保证每次请求都会提高图片质量。

此图片入口暂不提供显式 `minimal` 或 `medium` 的准确映射：`minimal` / `low` 会作为 `LOW` 发送，`medium` 不会覆盖模型默认值。请勿用这些值来控制新模型的强度。

`image_search=true` 让模型可以参考 Google Search 的搜索结果，不保证每次请求都会实际搜索，也不等于调用专用图片搜索。搜索是否可用取决于模型和接入资源。

## 响应与用量

同步响应示例，图片内容以占位字符串展示，不能直接解码此占位值：

```json theme={null}
{
  "created": 1791782400,
  "data": [{ "b64_json": "<BASE64_IMAGE>" }],
  "generate_image": 1,
  "usage": {
    "input_tokens": 100,
    "input_tokens_details": {
      "text_tokens": 60,
      "image_tokens": 40,
      "cached_tokens": 30,
      "cached_tokens_details": { "text_tokens": 20, "image_tokens": 10 }
    },
    "output_tokens": 1132,
    "output_tokens_details": { "image_tokens": 1120, "text_tokens": 7 },
    "total_tokens": 1232
  }
}
```

| 字段 | 含义 |
| - | - |
| `data[].b64_json` | 最终图片的 base64；解码后保存为图片文件 |
| `generate_image` | 实际返回的最终图片数量；不计入思考过程中的临时图片 |
| `input_tokens` | 总输入 token，包含缓存命中的部分 |
| `input_tokens_details.text_tokens` / `image_tokens` | 文本 / 图片总输入 token，均包含对应的缓存部分 |
| `input_tokens_details.cached_tokens` | 本次命中的缓存 token 总量；0 表示未命中 |
| `input_tokens_details.cached_tokens_details.text_tokens` / `image_tokens` | 文本 / 图片缓存命中明细 |
| `output_tokens` | 图片、普通文本及思考的输出总量 |
| `output_tokens_details.image_tokens` | 最终图片输出 token |
| `output_tokens_details.text_tokens` | 此 Gemini 图片入口中的思考 token，不是普通说明文字的 token |
| `total_tokens` | 上游返回的总 token 用量 |

普通文本输出量为 `output_tokens - output_tokens_details.image_tokens - output_tokens_details.text_tokens`。上例分别是图片 1120、普通文本 5、思考 7 token。

计费时，普通文本输入为 `60 - 20 = 40` token，普通图片输入为 `40 - 10 = 30` token；文本缓存 20 和图片缓存 10 分别按缓存价格计算，不会再次按普通输入计费。缓存命中由实际 `usage` 确认，重复发送提示词不保证命中。若上游只提供缓存总量，平台会保留总量并在输入数量范围内补齐拆分，不能据此判断缓存的精确来源。

不同模型及分辨率的图片 token 量可能不同；以上数字仅演示字段和计算关系，不代表固定单张价格。实际单价使用平台模型页面展示的价格。

## 异步调用

将请求路径改为 `/v1/images/generations/async`，图片参数保持一致。提交后用 `GET /v1/images/generations/{task_id}` 查询状态；任务完成后从 `data[].url` 下载图片。

完整提交、轮询和保存示例见[异步图片生成](https://quwan-b8010aef.mintlify.site/api-reference/examples/images/async-image.md)。Gemini 单张生成的 `n=1` 限制和分辨率要求同样适用。

## Gemini 原生入口

需要原生消息结构或多轮上下文时，使用 `generateContent`。原生响应与同步图片入口的响应结构不同，不能从原生响应读取 `data[].b64_json`。

```bash theme={null}
curl --request POST 'https://api.tokenops.ai/v1beta/models/gemini-nano-banana-2.1:generateContent' \
  --header "Authorization: Bearer $TOKENOPS_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "contents": [{ "role": "user", "parts": [{ "text": "生成一张清晨海边的咖啡馆照片" }] }],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "imageConfig": { "aspectRatio": "16:9", "imageSize": "1K" }
    }
  }' --output native-result.json
```

原生图片位于 `candidates[].content.parts[].inlineData.data`，格式由 `inlineData.mimeType` 给出。选取最终图片时排除 `thought=true` 的部分；不要假定第一段内容一定是图片。

原生参考图使用 `parts[].inlineData`：`mimeType` 填图片 MIME 类型，`data` 填裸 base64。多轮编辑时通过 `contents` 提交完整历史，保留模型返回的图片和其他必要内容，不仅发送上一轮的文字描述。

## 常见问题

* **HTTP 400**：检查模型名、非空 prompt、`n=1`、未启用流式，以及模型支持的分辨率和比例。不要给 2.1 传 `512`。
* **HTTP 401 / 403**：检查 API Key 和目标入口是否匹配、Key 是否有权限。
* **HTTP 501「未实现」**：当前接入资源尚未支持该入口，请联系平台支持；更换 `size` 或重复请求不能解决。
* **没有图片或缺少 usage**：不能作为成功生图处理；平台会返回错误。安全限制或仅返回文字也可能导致没有图片。
* **请求耗时较长**：复杂构图、参考图、高分辨率或高思考强度可能增加耗时。同步示例设置了 300 秒客户端超时；需要持续获取结果时使用异步接口，避免盲目重复提交造成多次生成。

## 参考文档

* [Google Gemini 图片生成](https://ai.google.dev/gemini-api/docs/generate-content/image-generation)
* [Google Vertex 图片生成](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/capabilities/image-generation)
* [Nano Banana 2.1 模型说明](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/gemini/nano-banana-2-1)


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