Nano Banana Pro 图片编辑 API

Nano Banana Pro（gemini-3-pro-image）可以按文字指令修改图片，或把最多 14 张参考图合成一张新图。老张API按次计费，单价不随分辨率和参考图数量变化。

编辑能力

项目	内容
模型 ID	`gemini-3-pro-image`
推荐端点	Gemini 原生的 `generateContent`：指令和图片放在同一条消息的 `parts` 里，用 `imageConfig` 设置比例和分辨率
其他端点	已有 OpenAI SDK 代码可以调用 `/v1/chat/completions` 编辑，但不能设置比例和分辨率
价格	按次计费，2026 年 9 月 24 日公开价格配置为 $0.09/次，见模型与价格
扣费	上游返回 HTTP 200 即扣一次，没有返回图片也扣费，见计费规则
参考图	最多 14 张：高保真物体最多 6 张，人物一致性参考最多 5 张，风格参考最多 3 张
图片输入	原生格式用 `inlineData`（Base64）或 `fileData`（公网 URL）；OpenAI 兼容格式用 `image_url`
分辨率 `imageSize`	`1K`、`2K`、`4K`，K 必须大写；不传时为 `1K`
比例 `aspectRatio`	`1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9`、`21:9`
返回图片	原生格式在 `candidates[0].content.parts[]` 的 `inlineData` 中（Base64）；OpenAI 兼容格式是 `message.content` 中的 data URL

参考图上限来自 Google 图像生成文档。请求里不需要标注每张图属于哪一类，在指令中说明每张图的用途即可。各比例在 1K、2K、4K 下的像素尺寸见 Nano Banana Pro 图像生成。

调用前准备

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

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

再把 Nano Banana 总览中的 nano_banana.py 保存到当前目录。本页的 Python 示例导入它，cURL 示例也用它把响应文件转成图片：

post()：发送带鉴权的请求
read_image()：读取本地 PNG、JPEG 或 WebP 图片
save_images()：从原生响应的 inlineData 或 OpenAI 兼容响应的 data URL 中取出图片并保存

示例使用 Authorization: Bearer 请求头。Gemini 原生格式也接受 x-goog-api-key 请求头；不要把密钥写进 URL 查询参数（例如 ?key=），URL 容易被日志、代理和浏览器历史记录下来。

用本地图片编辑

请求发到 POST /v1beta/models/gemini-3-pro-image:generateContent。把本地图片编码为 inlineData，和编辑指令放在同一条消息的 parts 中，mimeType 必须与图片的实际格式一致。下面把一张图改成雨夜风格，输出 16:9 的 2K 图片：

cURL
Python

IMAGE=photo.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"}
  }
}' > pro-edit-request.json

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" \
  --data-binary @pro-edit-request.json \
  -o pro-edit.json

python nano_banana.py pro-edit.json pro-edit

import sys

from nano_banana import post, read_image, save_images

ASPECT_RATIO = "16:9"  # 10 种比例之一
IMAGE_SIZE = "2K"      # 1K、2K 或 4K，K 必须大写

if not 1 <= len(sys.argv) - 2 <= 14:
    raise SystemExit('用法：python pro_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-pro-image:generateContent", {
    "contents": [{"role": "user", "parts": parts}],
    "generationConfig": {
        "responseModalities": ["IMAGE"],
        "imageConfig": {"aspectRatio": ASPECT_RATIO, "imageSize": IMAGE_SIZE},
    },
})
save_images(result, "pro-edit")

Python 示例保存为 pro_edit.py 后运行：

python pro_edit.py "把画面改成赛博朋克风格的雨夜，霓虹灯更强烈，保留建筑轮廓和构图" photo.png

成功后当前目录会出现 pro-edit-1.png 等文件，扩展名随返回的图片格式变化。4K 请求耗时更长，示例的超时时间为 300 秒。

合成多张图片

pro_edit.py 可以一次传入多张图片，图片按命令行顺序追加到 parts。指令里用「第一张图」「第二张图」指代，说明每张图提供什么（主体、服装、场景或风格），以及需要保留的细节：

python pro_edit.py "让第一张图中的模特穿上第二张图里的外套，站在第三张图的街道上，保留外套的颜色和纹理" model.jpg jacket.png street.jpg
python pro_edit.py "按第三张图的水彩风格，把第一张图的商品放进第二张图的客厅" product.png living-room.jpg watercolor.png

商品换背景、服装试穿、室内设计效果图和海报合成都可以用这种写法。要继续修改结果时，把上一次输出的文件作为下一次的输入，例如 python pro_edit.py "把灯光调暖一些，其余不变" pro-edit-1.png。

使用公网图片 URL

原生格式可以用 fileData 直接传入图片 URL，不必先下载再编码：

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": [
        {"fileData": {"mimeType": "image/png", "fileUri": "https://example.com/your-image.png"}},
        {"text": "在背景中加入日落时的海面，保留前景人物的姿势和服装"}
      ]
    }],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {"aspectRatio": "16:9", "imageSize": "4K"}
    }
  }' \
  -o pro-url-edit.json

python nano_banana.py pro-url-edit.json pro-url-edit

把 https://example.com/your-image.png 替换为你的图片 URL，并让 mimeType 与图片格式一致。图片地址必须能被 Google 的服务器从公网直接访问，不能有 Cloudflare 验证、验证码或 User-Agent 检测等访问限制；访问受限的图片请改用上一节的 inlineData 写法。

OpenAI 兼容格式

已有 OpenAI SDK 代码时，改三处即可：

base_url 设为 https://api.laozhang.ai/v1
model 改为 gemini-3-pro-image
编辑指令和图片放进同一条 user 消息的 content 数组

这种格式不能设置比例和分辨率。Python 示例关闭了 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": [
        {"type": "text", "text": "给画面中的猫戴上一顶小巫师帽，保持姿势、毛色和背景不变"},
        {"type": "image_url", "image_url": {"url": "https://example.com/your-image.jpg"}}
      ]
    }]
  }' \
  -o pro-openai-edit.json

python nano_banana.py pro-openai-edit.json pro-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 pro_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-pro-image",
    messages=[{"role": "user", "content": content}],
)
save_images(response.model_dump(), "pro-openai-edit")

cURL 示例中的 https://example.com/your-image.jpg 需要替换为能被公网直接访问的图片 URL。Python 示例保存为 pro_openai_edit.py 后，传入本地图片路径运行，它会把图片转成 data URL。

编辑指令怎么写

先写要改的内容，再写必须保留的内容，例如「把背景换成海边日落，保留人物的姿势、服装和光线方向」。
多张图片时按顺序称为第一张图、第二张图，并说明每张图提供的是主体、服装、场景还是风格。
要在图中写字时，把文字原样放进引号，并说明位置和字体风格。
复杂的改动分几次完成，每次以上一次的结果作为输入，比一次写很多要求更容易控制。

常见错误

现象	处理方法
401	检查 `Authorization` 头和 API Key，不要使用账号 AccessToken
400	检查 JSON 结构、`mimeType` 与图片实际格式是否一致，`imageSize` 是否为大写 K，比例是否在 10 种之内，参考图是否超过 14 张
404 或模型不可用	核对请求路径、完整模型 ID `gemini-3-pro-image` 和令牌分组
使用 `fileData` 的请求失败	确认图片 URL 能从公网直接下载、`mimeType` 与格式一致；仍失败时改用 `inlineData`
429、5xx 或超时	先在调用日志确认请求状态，再决定是否重试
HTTP 200 但没有图片	已按一次调用扣费，不要原样重试；查看返回的文字和 `finishReason`，在指令中明确要求修改图片，并去掉可能触发安全策略的内容后再提交

编辑请求同样按次计费，HTTP 200 但没有图片也扣费：

参考图或指令涉及版权 IP、敏感人物或敏感内容时，Google 不生成图片，也不返回错误码；原样重试通常仍被拦截，每次都会扣费。
客户端遇到没有图片的响应时停止自动重试，先检查参考图和指令。原因与避免方法见避免没有图片的扣费。
图片请求耗时较长，客户端超时不代表服务端已停止处理。立即重复提交可能多生成一次，并重复计费。

常见问题

可以用 `/v1/images/edits` 编辑吗？

不可以。Nano Banana Pro 的编辑使用 Gemini 原生的 generateContent 或 OpenAI 兼容的 /v1/chat/completions，不使用 Images API 的编辑接口。

只想改图片的一部分，需要遮罩吗？

不需要，请求里也没有遮罩参数。Google 把这种写法称为语义遮罩：在指令中写清要改的元素，并说明其余内容保持不变，例如「只把蓝色沙发换成棕色皮沙发，房间里的其他物品、构图和光线保持不变」。更多写法见编辑指令怎么写。

不传 `aspectRatio` 时输出什么比例？

Google 的默认行为是让输出尺寸跟随输入图片。想保持原图比例，从 imageConfig 中去掉 aspectRatio，只保留 imageSize；本页示例固定传了 16:9，可以改成需要的比例或直接删掉。各比例在 1K、2K、4K 下的像素尺寸见 Nano Banana Pro 图像生成。

开始使用

图像生成与编辑 API

视频生成 API

文本 API

多模态与音频 API

Nano Banana Pro 图片编辑 API

编辑能力

调用前准备

用本地图片编辑

合成多张图片

使用公网图片 URL

OpenAI 兼容格式

编辑指令怎么写

常见错误

常见问题

可以用 `/v1/images/edits` 编辑吗？

只想改图片的一部分，需要遮罩吗？

不传 `aspectRatio` 时输出什么比例？

相关文档与来源

​编辑能力

​调用前准备

​用本地图片编辑

​合成多张图片

​使用公网图片 URL

​OpenAI 兼容格式

​编辑指令怎么写

​常见错误

​常见问题

​可以用 /v1/images/edits 编辑吗？

​只想改图片的一部分，需要遮罩吗？

​不传 aspectRatio 时输出什么比例？

​相关文档与来源

编辑能力

调用前准备

用本地图片编辑

合成多张图片

使用公网图片 URL

OpenAI 兼容格式

编辑指令怎么写

常见错误

常见问题

可以用 `/v1/images/edits` 编辑吗？

只想改图片的一部分，需要遮罩吗？

不传 `aspectRatio` 时输出什么比例？

相关文档与来源