Nano Banana Pro API：1K–4K 图像生成

Nano Banana Pro（gemini-3-pro-image）适合复杂指令、精确文字渲染和专业素材，在老张API可以生成 1K–4K 图片并开启 Google 搜索接地，按次计费。

能力与参数

项目	内容
模型 ID	`gemini-3-pro-image`（稳定版）
官方名称	Google Gemini 3 Pro Image
价格	按次计费，2026 年 9 月 24 日公开价格配置为 $0.09/次，最新价格见模型与价格
扣费	上游返回 HTTP 200 即扣一次，没有返回图片也扣费，见计费规则
调用方式	Gemini 原生的 `generateContent` 可设置比例和分辨率；OpenAI 兼容的 `/v1/chat/completions` 输出 1K 图片
图片编辑	修改已有图片或合成多张参考图，见 Nano Banana Pro 图片编辑 API
分辨率 `imageSize`	`1K`、`2K`、`4K`；不传时为 `1K`
比例 `aspectRatio`	`1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9`、`21:9`，共 10 种
参考图	最多 14 张：高保真物体最多 6 张，人物一致性参考最多 5 张，风格参考最多 3 张
思考模式	默认启用，API 中不能关闭
Google 搜索接地	支持

Nano Banana 2 同样默认启用思考模式、支持搜索接地，还多支持 0.5K 分辨率和 4 种超宽、超高比例。能力依据 Google 图像生成文档，五个模型的对比见 Nano Banana 总览。 Google 已于 2026 年 6 月 25 日停止 gemini-3-pro-image-preview（见 Google 弃用页）。在老张API，-preview ID 会映射到对应的正式 ID，请直接使用正式 ID gemini-3-pro-image。 Google 文档列出的输出像素尺寸如下，imageSize 必须使用大写 K：

比例	1K	2K	4K
1:1	1024×1024	2048×2048	4096×4096
2:3	848×1264	1696×2528	3392×5056
3:2	1264×848	2528×1696	5056×3392
3:4	896×1200	1792×2400	3584×4800
4:3	1200×896	2400×1792	4800×3584
4:5	928×1152	1856×2304	3712×4608
5:4	1152×928	2304×1856	4608×3712
9:16	768×1376	1536×2752	3072×5504
16:9	1376×768	2752×1536	5504×3072
21:9	1584×672	3168×1344	6336×2688

价格与能力一览

分辨率	生成	编辑
1K	$0.09/次	$0.09/次
2K	$0.09/次	$0.09/次
4K	$0.09/次	$0.09/次

价格为 2026 年 9 月 24 日公开价格配置，核对日期 2026 年 10 月 10 日；分辨率和参考图数量不改变单价，Google 搜索接地按检索次数另收 $0.014。模型来自 Google 官方渠道，按次线路以固定单价计费，低于 Google 按 token 计费的 1K–4K 单张价格。

能力	支持情况
需要 Google 账号	不需要，只用老张API密钥
文生图与图生图编辑	都支持，同价；编辑见 Nano Banana Pro 图片编辑 API
参考图	最多 14 张
一次出图	每次请求一张；多张分多次请求
分辨率与比例	1K、2K、4K；10 种比例（Gemini 原生格式）
协议	Gemini 原生 `generateContent`，或 OpenAI 兼容 `/v1/chat/completions`
并发	平台不限制，`429` 来自上游容量，见并发与 429
失败扣费	HTTP 200 无图扣一次；429、5xx 未进入生成不扣费，见扣费与失败规则

调用前准备

在令牌管理创建 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 保存

示例使用 Authorization: Bearer 请求头。Gemini 原生格式也接受 x-goog-api-key 请求头；不要把密钥写进 URL 查询参数（例如 ?key=）。

生成图片

下面生成一张 16:9 的 4K 图片。4K 请求耗时更长，示例把超时设为 300 秒。

cURL
Python

curl --fail-with-body --max-time 300 \
  "https://api.laozhang.ai/v1beta/models/gemini-3-pro-image:generateContent" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{"text": "生成一张图片：黄昏时分的未来城市天际线，玻璃幕墙反射晚霞，街道上方有悬浮列车，电影感构图"}]
    }],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {"aspectRatio": "16:9", "imageSize": "4K"}
    }
  }' \
  -o pro-generate.json

python nano_banana.py pro-generate.json pro-generate

from nano_banana import post, save_images

result = post("/v1beta/models/gemini-3-pro-image:generateContent", {
    "contents": [{
        "role": "user",
        "parts": [{"text": "生成一张图片：黄昏时分的未来城市天际线，玻璃幕墙反射晚霞，街道上方有悬浮列车，电影感构图"}],
    }],
    "generationConfig": {
        "responseModalities": ["IMAGE"],
        "imageConfig": {"aspectRatio": "16:9", "imageSize": "4K"},
    },
})
save_images(result, "pro-generate")

成功后会得到 pro-generate-1.png 等文件，扩展名随返回的图片格式变化。

编辑图片

把本地图片编码为 inlineData，和编辑指令放在同一条消息的 parts 中，mimeType 必须与图片的实际格式一致。下面把上一步生成的图片改成雨夜风格（文件名以实际保存的为准）：

from nano_banana import post, read_image, save_images

mime, data = read_image("pro-generate-1.png")  # 替换为你的图片路径

result = post("/v1beta/models/gemini-3-pro-image:generateContent", {
    "contents": [{
        "role": "user",
        "parts": [
            {"text": "把画面改成赛博朋克风格的雨夜，霓虹灯更强烈，保留建筑轮廓和构图"},
            {"inlineData": {"mimeType": mime, "data": data}},
        ],
    }],
    "generationConfig": {
        "responseModalities": ["IMAGE"],
        "imageConfig": {"aspectRatio": "16:9", "imageSize": "2K"},
    },
})
save_images(result, "pro-edit")

成功后会得到 pro-edit-1.png 等文件。多图合成（最多 14 张参考图）、公网图片 URL 输入、OpenAI 兼容格式的编辑写法和常见错误，见 Nano Banana Pro 图片编辑 API。

用 OpenAI 兼容格式生成

已有 OpenAI SDK 代码时，把 base_url 设为 https://api.laozhang.ai/v1，model 改为 gemini-3-pro-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-pro-image",
    "stream": false,
    "messages": [
      {"role": "user", "content": "生成一张图片：极简风格的咖啡馆菜单海报，标题为「今日特调」，列出三款饮品和价格"}
    ]
  }' \
  -o pro-openai.json

python nano_banana.py pro-openai.json pro-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-pro-image",
    messages=[{
        "role": "user",
        "content": "生成一张图片：极简风格的咖啡馆菜单海报，标题为「今日特调」，列出三款饮品和价格",
    }],
)
save_images(response.model_dump(), "pro-openai")

用 OpenAI 兼容格式编辑图片时，把图片放进 content 数组的 image_url，写法见 Nano Banana Pro 图片编辑 API。

搜索接地

开启 Google 搜索接地后，模型会先搜索实时信息再生成图片，适合天气图表、近期事件信息图等依赖最新数据的任务。在请求中加入 googleSearch 工具；示例同时请求文字和图片，以便读取模型对搜索结果的说明。

cURL
Python

curl --fail-with-body --max-time 300 \
  "https://api.laozhang.ai/v1beta/models/gemini-3-pro-image:generateContent" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{"text": "搜索旧金山未来 5 天的天气预报，做成一张简洁现代的天气图表"}]
    }],
    "tools": [{"googleSearch": {}}],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "imageConfig": {"aspectRatio": "16:9"}
    }
  }' \
  -o pro-grounded.json

python nano_banana.py pro-grounded.json pro-grounded

from nano_banana import post, save_images

result = post("/v1beta/models/gemini-3-pro-image:generateContent", {
    "contents": [{
        "role": "user",
        "parts": [{"text": "搜索旧金山未来 5 天的天气预报，做成一张简洁现代的天气图表"}],
    }],
    "tools": [{"googleSearch": {}}],
    "generationConfig": {
        "responseModalities": ["TEXT", "IMAGE"],
        "imageConfig": {"aspectRatio": "16:9"},
    },
})
save_images(result, "pro-grounded")
for part in result["candidates"][0]["content"]["parts"]:
    if "text" in part and not part.get("thought"):
        print(part["text"])

图片和文字都在 candidates[0].content.parts 中；搜索来源位于 candidates[0].groundingMetadata。

同样的请求把模型换成 gemini-3.1-flash-image 即可用于 Nano Banana 2；Nano Banana 2 Lite 不支持搜索接地。
向最终用户展示接地结果时，需要按 Google 条款展示搜索建议。
搜索接地按检索次数另外计费，每次 $0.014；检索次数由模型决定，以调用日志为准，见 Nano Banana 总览的计费规则。

常见问题

要不要从 Pro 换成 Nano Banana 2？

多数任务可以先试 Nano Banana 2（gemini-3.1-flash-image）：请求结构相同，切换只改模型 ID，单价更低。依赖世界知识、多语言文字和精确品牌细节的成片，或编辑时需要风格参考图、最多 5 张人物参考图时，继续用 Pro。切换前用自己的提示词和图片在两个模型上各试几次，逐项差异见从 Nano Banana Pro 切换。

思考模式能关闭吗？会影响价格吗？

不能关闭。Google 说明 Gemini 3 图像模型默认启用思考，API 中无法关闭；thinkingLevel 只能调整 Nano Banana 2 和 2 Lite 的思考级别，传给 Pro 不会生效。思考时模型会生成临时图片检验构图，这些图片可能和最终结果一起返回，最后一张是最终结果，处理方法见一次请求能生成多张图吗。 Pro 按次计费，思考多少都不改变单价。

图片里的文字写错或变形怎么办？

Google 建议先让模型生成要放进图片的文字，确认无误后，再要求它生成包含这段文字的图片。提示词里把要出现的文字原样放进引号，并说明位置和字体风格，写法示例见编辑指令怎么写。仍有错字时，把结果图作为输入，只要求修改那一处文字。

开始使用

图像生成与编辑 API

视频生成 API

文本 API

多模态与音频 API

Nano Banana Pro API：1K–4K 图像生成

能力与参数

价格与能力一览

调用前准备

生成图片

编辑图片

用 OpenAI 兼容格式生成

搜索接地

常见问题

要不要从 Pro 换成 Nano Banana 2？

思考模式能关闭吗？会影响价格吗？

图片里的文字写错或变形怎么办？

相关文档

​能力与参数

​价格与能力一览

​调用前准备

​生成图片

​编辑图片

​用 OpenAI 兼容格式生成

​搜索接地

​常见问题

​要不要从 Pro 换成 Nano Banana 2？

​思考模式能关闭吗？会影响价格吗？

​图片里的文字写错或变形怎么办？

​相关文档

能力与参数

价格与能力一览

调用前准备

生成图片

编辑图片

用 OpenAI 兼容格式生成

搜索接地

常见问题

要不要从 Pro 换成 Nano Banana 2？

思考模式能关闭吗？会影响价格吗？

图片里的文字写错或变形怎么办？

相关文档