> ## 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 图片编辑 API（Standard）

> gemini-2.5-flash-image 的图片编辑与多图合成写法。Google 已弃用该模型，老张API暂时仍可调用，本页说明如何尽快迁移到 Nano Banana 2。

<Warning>
  **`gemini-2.5-flash-image` 已被 Google 弃用，停止日期说法不一（弃用页为 2027 年 3 月 15 日，价格页仍写 2026 年 10 月 2 日）。老张API暂时仍可调用，但随时可能停止，请尽快迁移。**

  * 停止日期见 [Google 弃用页](https://ai.google.dev/gemini-api/docs/deprecations)。截至 2026 年 10 月 5 日，老张API仍按原价 \$0.02/次提供该模型，不保证继续提供的期限。
  * 迁移目标是 Nano Banana 2（`gemini-3.1-flash-image`，2026 年 9 月 24 日公开价格配置为 \$0.055/次）。
  * 本页的编辑请求只需把 `model` 改为 `gemini-3.1-flash-image`，其余写法和结果解析不变，详见[迁移到新模型](#迁移到新模型)。
</Warning>

Nano Banana Standard（`gemini-2.5-flash-image`）可以按文字指令编辑图片、把多张图合成一张，只输出 1K，老张API按次计费。下文同时给出迁移到新模型的改法。

| 项目 | 内容 |
| - | - |
| 模型 ID | `gemini-2.5-flash-image` |
| 名称 | Nano Banana，即 Google 的 Gemini 2.5 Flash Image；本站标为 Standard，以区别于 Nano Banana 2 和 Pro |
| 端点 | OpenAI 兼容的 `POST /v1/chat/completions` |
| 输入 | 编辑指令和原图放进同一条 user 消息 |
| 返回 | `message.content` 中的 data URL，解码后保存为文件 |
| 输出 | 仅 1K |
| 价格 | 按次计费，2026 年 9 月 24 日公开价格配置为 \$0.02/次，见[模型与价格](/models) |
| 扣费 | 上游返回 HTTP 200 即扣一次，没有返回图片也扣费，见[计费规则](/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
```

再把 [Nano Banana 总览](/api-capabilities/nano-banana-image#共用代码)中的 `nano_banana.py` 保存到当前目录。本页的 Python 示例导入它，cURL 示例也用它把响应文件转成图片：

* `post()`：发送带鉴权的请求
* `read_image()`：读取本地 PNG、JPEG 或 WebP 图片
* `save_images()`：从返回内容中取出 data URL 并保存为图片

## 编辑一张图片

编辑指令和图片放在同一条 user 消息的 `content` 数组里：先放 `text`，再放 `image_url`。本地图片先转成 `data:<MIME 类型>;base64,<数据>` 形式的 data URL。指令里写清要改什么、保留什么。

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    IMAGE=photo.png   # 替换为你的图片路径

    # 生成 data URL，并用 jq 写入请求文件（需要 jq 1.6 及以上）
    { printf 'data:%s;base64,' "$(file --mime-type -b "$IMAGE")"; base64 < "$IMAGE" | tr -d '\n'; } > image-url.txt

    jq -n --rawfile url image-url.txt '{
      model: "gemini-2.5-flash-image",
      stream: false,
      messages: [{
        role: "user",
        content: [
          {type: "text", text: "把背景换成浅灰色摄影棚，保留主体的外观、颜色和位置"},
          {type: "image_url", image_url: {url: $url}}
        ]
      }]
    }' > standard-edit-request.json

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

    python nano_banana.py standard-edit.json standard-edit
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import sys

    from nano_banana import post, read_image, save_images

    MODEL = "gemini-2.5-flash-image"  # 迁移时改为 gemini-3.1-flash-image
    MAX_IMAGES = 3                    # Standard 建议不超过 3 张；Nano Banana 2 可改为 14

    if not 1 <= len(sys.argv) - 2 <= MAX_IMAGES:
        raise SystemExit(f'用法：python standard_edit.py "编辑指令" 图片1 [图片2 ...]，最多 {MAX_IMAGES} 张')
    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}"}})

    result = post("/v1/chat/completions", {
        "model": MODEL,
        "stream": False,
        "messages": [{"role": "user", "content": content}],
    })
    save_images(result, "standard-edit")
    ```
  </Tab>
</Tabs>

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

```bash theme={null}
python standard_edit.py "把背景换成浅灰色摄影棚，保留主体的外观、颜色和位置" photo.png
```

成功后当前目录会出现 `standard-edit-1.png` 等文件，扩展名随返回的图片格式变化。

## 合成多张图片

把多张图片按顺序追加到 `content`，指令里用「第一张图」「第二张图」指代，并说明每张图的用途和要保留的细节。

[Google 图像生成文档](https://ai.google.dev/gemini-api/docs/image-generation)说明，`gemini-2.5-flash-image` 在输入不超过 3 张图时效果最好，上面的脚本因此最多接受 3 张。

```bash theme={null}
python standard_edit.py "把第一张图中的杯子放到第二张图的木桌上，保留杯子的颜色和花纹" cup.png table.jpg
python standard_edit.py "让第一张图中的人物穿上第二张图里的外套，背景换成第三张图的街道" person.jpg jacket.png street.jpg
```

需要更多参考图时改用 Nano Banana 2 或 Nano Banana Pro，两者最多都支持 14 张。

## 使用公网图片 URL

图片已经在公网上时，不必转成 data URL，直接把地址填进 `image_url.url`：

```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-2.5-flash-image",
    "stream": false,
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "在天空中加一道彩虹，其余内容保持不变"},
        {"type": "image_url", "image_url": {"url": "https://example.com/your-image.png"}}
      ]
    }]
  }' \
  -o standard-url-edit.json

python nano_banana.py standard-url-edit.json standard-url-edit
```

把 `https://example.com/your-image.png` 替换为你的图片地址。图片需要能被公网直接访问；需要登录或有访问限制的图片，请改用上一节的本地图片写法。

## 读取返回结果

结果图在 `choices[0].message.content` 中，是 `data:image/png;base64,...` 形式的 data URL，前后可能带有 Markdown 图片语法或说明文字，例如：

```json theme={null}
{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "![image](data:image/png;base64,iVBORw0KGgo...)"
    },
    "finish_reason": "stop"
  }]
}
```

`save_images()` 会找出内容中的全部 data URL，按其中的图片类型保存为 PNG、JPEG 或 WebP 文件，并补齐 Base64 末尾缺少的 `=`。内容里没有图片时，它会显示返回内容并退出，便于判断原因。

## 编辑指令怎么写

* 先写要改的内容，再写必须保留的内容，例如「把背景换成浅灰色摄影棚，保留人物的姿势、服装和光线方向」。
* 多张图片时按顺序称为第一张图、第二张图，并说明每张图的用途。
* 一次只提一两处修改。复杂的改动分几次完成，把上一次的结果作为下一次的输入。
* 可以直接用中文写指令。

## 迁移到新模型

下面三个模型都支持图片编辑，OpenAI 兼容格式的请求结构和返回结构与本页相同：

| 迁移目标 | 模型 ID | 适合的编辑任务 |
| - | - | - |
| Nano Banana 2（推荐） | `gemini-3.1-flash-image` | 大多数编辑任务；最多 14 张参考图，原生格式可设 0.5K–4K 和 14 种比例 |
| Nano Banana 2 Lite | `gemini-3.1-flash-lite-image` | 只需 1K、以单图编辑为主、看重单价 |
| Nano Banana Pro | `gemini-3-pro-image` | 复杂构图、精确文字渲染和专业成片 |

2026 年 9 月 24 日公开价格配置中，Nano Banana 2 Lite 为 \$0.025/次，Nano Banana Pro 为 \$0.09/次；五个模型的对比见 [Nano Banana 总览](/api-capabilities/nano-banana-image#模型对比)。

Google 弃用页给出的替代模型是 Nano Banana 2，[Google 图像生成文档](https://ai.google.dev/gemini-api/docs/image-generation)则建议 Standard 用户迁移到 Nano Banana 2 Lite。Lite 不针对多参考图和多轮连续编辑优化，依赖多图合成的集成请选 Nano Banana 2。

迁移步骤：

1. 把请求中的 `model` 改为目标模型 ID。使用本页的 `standard_edit.py` 时改 `MODEL`；迁移到 Nano Banana 2 或 Pro 后，可以把 `MAX_IMAGES` 调高到 14。
2. 用同样的图片和指令在新模型上各运行一次，检查编辑效果，并在[调用日志](/faq/call-logs)中核对模型 ID 和扣费。
3. 需要指定比例或 2K、4K 分辨率时，改用 Gemini 原生格式，写法见 [Nano Banana 2 API](/api-capabilities/nano-banana2-image#编辑图片) 或 [Nano Banana Pro 图片编辑 API](/api-capabilities/nano-banana-pro-image-edit)。Nano Banana 2 Lite 只输出 1K。

已经用 Gemini 原生格式调用 Standard 的集成，把 URL 中的模型名 `gemini-2.5-flash-image` 换成目标模型 ID 即可。

## 常见错误

| 现象 | 处理方法 |
| - | - |
| 401 | 检查 `Authorization: Bearer` 请求头和 API Key，不要使用账号 AccessToken |
| 400 | 检查 JSON 结构；data URL 须为 `data:<MIME 类型>;base64,<数据>`，MIME 类型要与图片实际格式一致 |
| 404 或提示模型不可用 | 核对请求路径、模型 ID 和令牌分组；如果其他都正确，说明 Standard 已停止，请改用迁移目标模型 |
| 调用 `/v1/images/edits` 失败 | Nano Banana 编辑使用 `/v1/chat/completions`，不使用 Images 编辑接口 |
| 429、5xx 或超时 | 先在调用日志中确认请求状态，再决定是否重试 |
| HTTP 200 但没有图片 | 已按一次调用扣费，不要原样重试；查看返回的文字，在指令中明确要求修改图片，并去掉可能触发安全策略的内容后再提交 |

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

* 原图或指令触发上游安全策略时，原样重试通常仍被拦截，每次都会扣费。原因与避免方法见[避免没有图片的扣费](/api-capabilities/nano-banana-image#避免没有图片的扣费)。
* 图片请求耗时较长，客户端超时不代表服务端已停止处理。立即重复提交可能多生成一次，并重复计费。

## 常见问题

### 10 月 2 日之后还能调用 Standard 吗？

目前还能。Google 价格页曾提示 `gemini-2.5-flash-image` 于 2026 年 10 月 2 日停止，弃用页截至 2026 年 10 月 8 日改列 2027 年 3 月 15 日；截至 2026 年 10 月 5 日，老张API仍可调用该模型，价格不变。

* 老张API不保证继续提供的期限，该模型随时可能停止。
* 停止后请求会失败，不会自动转到新模型；它不像 `-preview` ID 那样映射到正式 ID。

请尽快按[迁移到新模型](#迁移到新模型)修改 `model`，当前可用的模型见[模型与价格](/models)。

### 编辑时能指定输出比例或 2K、4K 分辨率吗？

比例可以，2K、4K 不行。OpenAI 兼容格式没有比例和分辨率参数，改用 Gemini 原生格式后：

* 用 `generationConfig.imageConfig.aspectRatio` 设置比例，共 10 种，取值见下表。
* 不设置比例时，Google 的默认行为是让输出尺寸跟随输入图片。
* Standard 只输出约 1K，不能传 `imageSize`。需要 2K、4K 时，迁移到 Nano Banana 2 或 Nano Banana Pro，再加上 `imageSize`。

| 方向 | 比例 |
| - | - |
| 方形 | `1:1` |
| 竖版 | `2:3`、`3:4`、`4:5`、`9:16` |
| 横版 | `3:2`、`4:3`、`5:4`、`16:9`、`21:9` |

### 旧代码里的 -preview 模型 ID 还能用吗？

不能。Google 已于 2026 年 1 月 15 日停止 `gemini-2.5-flash-image-preview`（见 [Google 弃用页](https://ai.google.dev/gemini-api/docs/deprecations)），老张API的模型列表中也没有这个 ID。

`gemini-2.5-flash-image` 本身也已过 Google 列出的停止日期、随时可能停止，请直接迁移到 Nano Banana 2（`gemini-3.1-flash-image`）。

## 相关文档与来源

* [Nano Banana 总览](/api-capabilities/nano-banana-image)：五个模型对比、共用代码与计费规则
* [Nano Banana 2 API](/api-capabilities/nano-banana2-image)：推荐的迁移目标，0.5K–4K、最多 14 张参考图
* [Nano Banana 2 Lite API](/api-capabilities/nano-banana-2-lite-api)：只需 1K 时的轻量模型
* [Nano Banana Pro 图片编辑 API](/api-capabilities/nano-banana-pro-image-edit)：复杂合成与 4K 输出
* [图像 API 选型与价格](/api-capabilities/image-generation-guide)：与其他图像模型比较
* [Google 弃用页](https://ai.google.dev/gemini-api/docs/deprecations)：`gemini-2.5-flash-image` 的停止日期与替代模型
* [Google 图像生成文档](https://ai.google.dev/gemini-api/docs/image-generation)：各模型的输入图片数量与迁移建议


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