> ## Documentation Index > Fetch the complete documentation index at: https://docs.laozhang.ai/llms.txt > Use this file to discover all available pages before exploring further. # Nano Banana 2 API：0.5K–4K 图像生成与编辑 > 调用 gemini-3.1-flash-image 生成和编辑 0.5K–4K 图片：14 种比例、最多 14 张参考图，附请求与保存代码。 Nano Banana 2（`gemini-3.1-flash-image`）是 Google 推荐用于大多数图像任务的模型，在老张API可以生成和编辑 0.5K–4K 图片，按次计费。 ## 能力与参数 | 项目 | 内容 | | - | - | | 模型 ID | `gemini-3.1-flash-image`（稳定版） | | 官方名称 | Google Gemini 3.1 Flash Image | | 特点 | 文字渲染稳定，擅长多参考图合成 | | 价格 | 按次计费，2026 年 9 月 24 日公开价格配置为 \$0.055/次，最新价格见[模型与价格](/models) | | 扣费 | 上游返回 HTTP 200 即扣一次，没有返回图片也扣费，见[计费规则](/api-capabilities/nano-banana-image#计费规则) | | 调用方式 | Gemini 原生的 `generateContent` 可设置比例和分辨率；OpenAI 兼容的 `/v1/chat/completions` 输出 1K 图片 | | 分辨率 `imageSize` | `512`（0.5K）、`1K`、`2K`、`4K`；不传时为 `1K` | | 比例 `aspectRatio` | `1:1`、`1:4`、`4:1`、`1:8`、`8:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9`、`21:9`，共 14 种 | | 参考图 | 最多 14 张：高保真物体最多 10 张，人物一致性参考最多 4 张 | | 思考模式 | 默认启用，级别 `minimal`（默认）或 `high` | | Google 搜索接地 | 支持网页搜索和图片搜索 | `imageSize` 是字符串，K 必须大写；0.5K 对应的取值是 `512`。以 1:1 为例，四档分辨率分别输出 512×512、1024×1024、2048×2048 和 4096×4096；其他比例的像素尺寸见 [Google 图像生成文档](https://ai.google.dev/gemini-api/docs/image-generation)，字段定义见 [Google generateContent 参考](https://ai.google.dev/api/generate-content)。 Google 已于 2026 年 6 月 25 日停止 `gemini-3.1-flash-image-preview`（见 [Google 弃用页](https://ai.google.dev/gemini-api/docs/deprecations)）。在老张API，`-preview` ID 会映射到对应的正式 ID，请直接使用正式 ID `gemini-3.1-flash-image`。五个 Nano Banana 模型的价格与能力对比见 [Nano Banana 总览](/api-capabilities/nano-banana-image)。 ## 调用前准备在[令牌管理](https://api.laozhang.ai/token)创建 API Key，计费模式选择「按量优先」（推荐）或「按次计费」：按量优先的令牌可以同时调用按量和按次计费的模型，按次计费的令牌只能调用按次计费的模型。无图响应与重试的计费说明见[计费规则](/api-capabilities/nano-banana-image#计费规则)。设置密钥并安装依赖： ```bash theme={null} export LAOZHANG_API_KEY="替换为你的老张API密钥" python -m pip install requests openai ``` 本页示例还需要 [Nano Banana 总览](/api-capabilities/nano-banana-image#共用代码)中的 `nano_banana.py`，请把它保存到当前目录。cURL 示例也用它把响应文件保存为图片： * `read_image()`：读取本地图片 * `save_images()`：从 Gemini 原生响应的 `parts[].inlineData` 或 OpenAI 兼容响应的 data URL 中取出 Base64 数据，解码后按 PNG、JPEG 或 WebP 保存 ## 生成图片下面生成一张 16:9 的 2K 图片。需要 4K 时把 `imageSize` 改为 `4K`，快速预览可以改为 `512`；比例从上表中任选。 ```bash theme={null} curl --fail-with-body --max-time 300 \ "https://api.laozhang.ai/v1beta/models/gemini-3.1-flash-image:generateContent" \ -H "Authorization: Bearer $LAOZHANG_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "contents": [{ "role": "user", "parts": [{"text": "生成一张图片：雨后傍晚的城市街角咖啡馆，暖色灯光映在湿润的路面上，招牌写着 BANANA CAFE"}] }], "generationConfig": { "responseModalities": ["IMAGE"], "imageConfig": {"aspectRatio": "16:9", "imageSize": "2K"} } }' \ -o nb2-generate.json python nano_banana.py nb2-generate.json nb2-generate ``` ```python theme={null} from nano_banana import post, save_images result = post("/v1beta/models/gemini-3.1-flash-image:generateContent", { "contents": [{ "role": "user", "parts": [{"text": "生成一张图片：雨后傍晚的城市街角咖啡馆，暖色灯光映在湿润的路面上，招牌写着 BANANA CAFE"}], }], "generationConfig": { "responseModalities": ["IMAGE"], "imageConfig": {"aspectRatio": "16:9", "imageSize": "2K"}, }, }) save_images(result, "nb2-generate") ``` 成功后会得到 `nb2-generate-1.png` 等文件，扩展名随返回的图片格式变化。 ## 编辑图片把本地图片编码为 `inlineData`，和编辑指令放在同一条消息的 `parts` 中。多张参考图按顺序追加，提示词里用「第一张图」「第二张图」指代；最多 14 张。 ```bash theme={null} IMAGE=nb2-generate-1.png # 替换为你的图片路径 # 生成 Base64 并用 jq 写入请求文件（需要 jq 1.6 及以上） base64 < "$IMAGE" | tr -d '\n' > image.b64 jq -n --arg mime "$(file --mime-type -b "$IMAGE")" --rawfile data image.b64 '{ contents: [{ role: "user", parts: [ {text: "把画面改成下雪的清晨，保留咖啡馆的结构、招牌文字和构图"}, {inlineData: {mimeType: $mime, data: $data}} ] }], generationConfig: { responseModalities: ["IMAGE"], imageConfig: {aspectRatio: "16:9", imageSize: "2K"} } }' > nb2-edit-request.json curl --fail-with-body --max-time 300 \ "https://api.laozhang.ai/v1beta/models/gemini-3.1-flash-image:generateContent" \ -H "Authorization: Bearer $LAOZHANG_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @nb2-edit-request.json \ -o nb2-edit.json python nano_banana.py nb2-edit.json nb2-edit ``` ```python theme={null} import sys from nano_banana import post, read_image, save_images if not 3 <= len(sys.argv) <= 16: raise SystemExit('用法：python nb2_edit.py "编辑指令" 图片1 [图片2 ...]，最多 14 张') prompt, paths = sys.argv[1], sys.argv[2:] parts = [{"text": prompt}] for path in paths: mime, data = read_image(path) parts.append({"inlineData": {"mimeType": mime, "data": data}}) result = post("/v1beta/models/gemini-3.1-flash-image:generateContent", { "contents": [{"role": "user", "parts": parts}], "generationConfig": { "responseModalities": ["IMAGE"], "imageConfig": {"aspectRatio": "16:9", "imageSize": "2K"}, }, }) save_images(result, "nb2-edit") ``` Python 示例保存为 `nb2_edit.py` 后，单图编辑可以直接使用上一步生成的图片（文件名以实际保存的为准），多图合成时换成你自己的图片： ```bash theme={null} python nb2_edit.py "把画面改成下雪的清晨，保留咖啡馆的结构、招牌文字和构图" nb2-generate-1.png python nb2_edit.py "让第一张图中的人物穿上第二张图里的外套，站在第三张图的街道上" person.jpg jacket.png street.jpg ``` ## OpenAI 兼容格式已有 OpenAI SDK 代码时，把 `base_url` 设为 `https://api.laozhang.ai/v1`，`model` 改为 `gemini-3.1-flash-image` 即可。这种格式不能设置比例和分辨率，文生图输出 1:1 的 1K 图片。示例关闭了 SDK 的自动重试，避免超时后重复生成和扣费。 ### 生成图片 ```bash theme={null} curl --fail-with-body --max-time 300 \ "https://api.laozhang.ai/v1/chat/completions" \ -H "Authorization: Bearer $LAOZHANG_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gemini-3.1-flash-image", "stream": false, "messages": [ {"role": "user", "content": "生成一张图片：木桌上的一杯拿铁，拉花是一只小猫，俯拍"} ] }' \ -o nb2-openai.json python nano_banana.py nb2-openai.json nb2-openai ``` ```python theme={null} import os from openai import OpenAI from nano_banana import save_images client = OpenAI( api_key=os.environ["LAOZHANG_API_KEY"], base_url="https://api.laozhang.ai/v1", timeout=300, max_retries=0, ) response = client.chat.completions.create( model="gemini-3.1-flash-image", messages=[{"role": "user", "content": "生成一张图片：木桌上的一杯拿铁，拉花是一只小猫，俯拍"}], ) save_images(response.model_dump(), "nb2-openai") ``` ### 编辑图片 ```bash theme={null} curl --fail-with-body --max-time 300 \ "https://api.laozhang.ai/v1/chat/completions" \ -H "Authorization: Bearer $LAOZHANG_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gemini-3.1-flash-image", "stream": false, "messages": [{ "role": "user", "content": [ {"type": "text", "text": "把这张图变成梵高《星月夜》风格的油画"}, {"type": "image_url", "image_url": {"url": "https://example.com/your-image.jpg"}} ] }] }' \ -o nb2-openai-edit.json python nano_banana.py nb2-openai-edit.json nb2-openai-edit ``` ```python theme={null} import os import sys from openai import OpenAI from nano_banana import read_image, save_images if len(sys.argv) < 3: raise SystemExit('用法：python nb2_openai_edit.py "编辑指令" 图片1 [图片2 ...]') prompt, paths = sys.argv[1], sys.argv[2:] content = [{"type": "text", "text": prompt}] for path in paths: mime, data = read_image(path) content.append({"type": "image_url", "image_url": {"url": f"data:{mime};base64,{data}"}}) client = OpenAI( api_key=os.environ["LAOZHANG_API_KEY"], base_url="https://api.laozhang.ai/v1", timeout=300, max_retries=0, ) response = client.chat.completions.create( model="gemini-3.1-flash-image", messages=[{"role": "user", "content": content}], ) save_images(response.model_dump(), "nb2-openai-edit") ``` cURL 示例中的 `https://example.com/your-image.jpg` 需要替换为你的图片 URL，图片要能被公网直接访问；本地图片请使用 Python 示例，它会把图片转成 data URL。 ## 从 Nano Banana Pro 切换只需将模型名从 `gemini-3-pro-image` 改为 `gemini-3.1-flash-image`，请求结构和响应解析不变。切换前核对以下差异： * **分辨率**：Nano Banana 2 多出 `512`（0.5K）；两者都支持 `1K`、`2K`、`4K`。 * **比例**：Nano Banana 2 多出 `1:4`、`4:1`、`1:8`、`8:1`，其余 10 种相同。 * **参考图**：两者最多都是 14 张，但分配不同。Nano Banana 2 为高保真物体 10 张、人物 4 张；Pro 为物体 6 张、人物 5 张，另有 3 张风格参考。 * **搜索接地**：两者都支持网页搜索，Nano Banana 2 还支持图片搜索。请求写法见 [Nano Banana Pro 的搜索接地示例](/api-capabilities/nano-banana-pro-image#搜索接地)；图片搜索的开启方式见本页[常见问题](#常见问题)。 * **单价**：两者不同，见 [Nano Banana 总览](/api-capabilities/nano-banana-image)。 ## 常见问题 ### 0.5K 分辨率怎么传？在 `generationConfig.imageConfig.imageSize` 中传字符串 `512`。0.5K 只有 Nano Banana 2 支持，也只能通过 Gemini 原生格式设置。 ### 思考级别怎么调？会影响价格吗？使用 Gemini 原生格式时，在 `generationConfig.thinkingConfig.thinkingLevel` 中设置，例如 `"thinkingConfig": {"thinkingLevel": "high"}`。 Nano Banana 2 和 Nano Banana 2 Lite 支持 `minimal`（默认）和 `high` 两档，用于在出图质量和响应速度之间取舍，老张API会原样传给上游。思考级别不改变单价：老张API只按次计费，用 `high` 时每次调用仍是 Nano Banana 2 的按次价格（Google 官方则会按思考 tokens 另外计费）。Nano Banana Pro 始终启用思考，不能调整级别。 ### 怎么开启图片搜索接地？有什么限制？在网页搜索接地的请求基础上，给 `googleSearch` 工具加上 `searchTypes`，同时列出 `webSearch` 和 `imageSearch`。请求的其余部分与 [Nano Banana Pro 的搜索接地示例](/api-capabilities/nano-banana-pro-image#搜索接地)相同： ```json theme={null} "tools": [{"googleSearch": {"searchTypes": {"webSearch": {}, "imageSearch": {}}}}] ``` 按 [Google generateContent 参考](https://ai.google.dev/api/generate-content)： * 不设置 `searchTypes` 时只启用网页搜索；只写 `imageSearch` 时只用图片搜索。 * 像上面这样两种都列出时，两种都可以用，每次是否检索、用哪一种由模型决定。 * `searchTypes` 必须写成对象，写成数组不会生效；生效时，响应的 `groundingMetadata` 中会出现 `imageSearchQueries`。 Google 列出的限制： * 图片搜索接地只有 Nano Banana 2 和 Nano Banana 2.1 支持。 * 目前不能把网页搜索到的真实人物图片用作参考。 * 向最终用户展示接地结果时，需要按 Google 条款展示搜索建议。开启搜索接地时，在按次单价之外每次检索另收 \$0.014，检索次数由模型决定，以调用日志为准，说明见 [Nano Banana 总览的计费规则](/api-capabilities/nano-banana-image#计费规则)。 ## 相关文档 * [Nano Banana 总览](/api-capabilities/nano-banana-image)：五个模型对比、两种调用方式与共用代码 * [Nano Banana 图片编辑 API（Standard）](/api-capabilities/nano-banana-image-edit#迁移到新模型)：把 `gemini-2.5-flash-image` 的编辑请求迁移到本模型 * [Nano Banana 2.1 API](/api-capabilities/nano-banana-2-1-image)：更新版，1K–4K，单价更低 * [Nano Banana 2 Lite API](/api-capabilities/nano-banana-2-lite-api)：只需 1K 时的轻量模型 * [Nano Banana Pro API](/api-capabilities/nano-banana-pro-image)：复杂构图、专业成片与搜索接地示例 * [Nano Banana Pro 图片编辑 API](/api-capabilities/nano-banana-pro-image-edit)：Pro 的多图合成与公网 URL 输入 * [Gemini 协议](/api-reference/gemini)：原生请求结构与 SDK 配置 * [Google 图像生成文档](https://ai.google.dev/gemini-api/docs/image-generation)：比例、像素尺寸与参考图上限 * [Google generateContent 参考](https://ai.google.dev/api/generate-content)：`imageConfig`、`thinkingConfig`、`googleSearch` 等字段定义 This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.