Nano Banana 2 API：0.5K–4K 图像生成与编辑

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/次，最新价格见模型与价格
扣费	上游返回 HTTP 200 即扣一次，没有返回图片也扣费，见计费规则
调用方式	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 图像生成文档，字段定义见 Google generateContent 参考。 Google 已于 2026 年 6 月 25 日停止 gemini-3.1-flash-image-preview（见 Google 弃用页）。在老张API，-preview ID 会映射到对应的正式 ID，请直接使用正式 ID gemini-3.1-flash-image。五个 Nano Banana 模型的价格与能力对比见 Nano Banana 总览。

调用前准备

在令牌管理创建 API Key，计费模式选择「按量优先」（推荐）或「按次计费」：按量优先的令牌可以同时调用按量和按次计费的模型，按次计费的令牌只能调用按次计费的模型。无图响应与重试的计费说明见计费规则。设置密钥并安装依赖：

export LAOZHANG_API_KEY="替换为你的老张API密钥"
python -m pip install requests openai

本页示例还需要 Nano Banana 总览中的 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；比例从上表中任选。

cURL
Python

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

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 张。

cURL
Python

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

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 后，单图编辑可以直接使用上一步生成的图片（文件名以实际保存的为准），多图合成时换成你自己的图片：

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 的自动重试，避免超时后重复生成和扣费。

生成图片

cURL
Python

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

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")

编辑图片

cURL
Python

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

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 的搜索接地示例；图片搜索的开启方式见本页常见问题。
单价：两者不同，见 Nano Banana 总览。

常见问题

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 的搜索接地示例相同：

"tools": [{"googleSearch": {"searchTypes": {"webSearch": {}, "imageSearch": {}}}}]

按 Google generateContent 参考：

不设置 searchTypes 时只启用网页搜索；只写 imageSearch 时只用图片搜索。
像上面这样两种都列出时，两种都可以用，每次是否检索、用哪一种由模型决定。
searchTypes 必须写成对象，写成数组不会生效；生效时，响应的 groundingMetadata 中会出现 imageSearchQueries。

Google 列出的限制：

图片搜索接地只有 Nano Banana 2 和 Nano Banana 2.1 支持。
目前不能把网页搜索到的真实人物图片用作参考。
向最终用户展示接地结果时，需要按 Google 条款展示搜索建议。

开启搜索接地时，在按次单价之外每次检索另收 $0.014，检索次数由模型决定，以调用日志为准，说明见 Nano Banana 总览的计费规则。

开始使用

图像生成与编辑 API

视频生成 API

文本 API

多模态与音频 API

Nano Banana 2 API：0.5K–4K 图像生成与编辑

能力与参数

调用前准备

生成图片

编辑图片

OpenAI 兼容格式

生成图片

编辑图片

从 Nano Banana Pro 切换

常见问题

0.5K 分辨率怎么传？

思考级别怎么调？会影响价格吗？

怎么开启图片搜索接地？有什么限制？

相关文档

​能力与参数

​调用前准备

​生成图片

​编辑图片

​OpenAI 兼容格式

​生成图片

​编辑图片

​从 Nano Banana Pro 切换

​常见问题

​0.5K 分辨率怎么传？

​思考级别怎么调？会影响价格吗？

​怎么开启图片搜索接地？有什么限制？

​相关文档

能力与参数

调用前准备

生成图片

编辑图片

OpenAI 兼容格式

生成图片

编辑图片

从 Nano Banana Pro 切换

常见问题

0.5K 分辨率怎么传？

思考级别怎么调？会影响价格吗？

怎么开启图片搜索接地？有什么限制？

相关文档