> ## 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 Pro 图片编辑 API

> 用 gemini-3-pro-image 编辑图片：最多 14 张参考图合成、1K–4K 输出与公网 URL 输入，附两种请求格式的示例。

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/次，见[模型与价格](/models) |
| 扣费 | 上游返回 HTTP 200 即扣一次，没有返回图片也扣费，见[计费规则](/api-capabilities/nano-banana-image#计费规则) |
| 参考图 | 最多 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 图像生成文档](https://ai.google.dev/gemini-api/docs/image-generation)。请求里不需要标注每张图属于哪一类，在指令中说明每张图的用途即可。各比例在 1K、2K、4K 下的像素尺寸见 [Nano Banana Pro 图像生成](/api-capabilities/nano-banana-pro-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` 保存到当前目录。本页的 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 图片：

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    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
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    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")
    ```
  </Tab>
</Tabs>

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

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

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

## 合成多张图片

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

```bash theme={null}
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，不必先下载再编码：

```bash theme={null}
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 的自动重试，避免超时后重复生成和扣费。

<Tabs>
  <Tab title="cURL">
    ```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-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
    ```
  </Tab>

  <Tab title="Python">
    ```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 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")
    ```
  </Tab>
</Tabs>

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 或超时 | 先在[调用日志](/faq/call-logs)确认请求状态，再决定是否重试 |
| HTTP 200 但没有图片 | 已按一次调用扣费，不要原样重试；查看返回的文字和 `finishReason`，在指令中明确要求修改图片，并去掉可能触发安全策略的内容后再提交 |

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

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

## 常见问题

### 可以用 `/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-capabilities/nano-banana-pro-image#能力与参数)。

## 相关文档与来源

* [Nano Banana Pro 图像生成](/api-capabilities/nano-banana-pro-image)：文生图、像素尺寸表与 Google 搜索接地
* [Nano Banana 总览](/api-capabilities/nano-banana-image)：五个模型对比、共用代码与计费规则
* [Nano Banana 2 API](/api-capabilities/nano-banana2-image)：单价更低的 0.5K–4K 模型
* [Gemini 协议](/api-reference/gemini)：原生请求结构与 Google Gen AI SDK 配置
* [Google 图像生成文档](https://ai.google.dev/gemini-api/docs/image-generation)：参考图上限、比例与像素尺寸
* [Google generateContent 参考](https://ai.google.dev/api/generate-content)：`inlineData`、`fileData`、`imageConfig` 等字段定义


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