Nano Banana API: image editing (Standard)

​

Before you start

1

Create an API key

In Token management, open the create-token dialog (创建令牌), set Billing mode (计费模式) to Usage first (按量优先, recommended) or Per-call (按次计费), and click Create (创建). Nano Banana models have only a per-call price: a Usage first key can call them as well as usage-based models, while a Per-call key calls only per-call models. The default group includes gemini-2.5-flash-image.

2

Set the key and install the dependencies

export LAOZHANG_API_KEY="sk-..."  # replace with your LaoZhang API key
python -m pip install openai requests

The cURL examples also need jq, for example brew install jq or sudo apt-get install jq.

3

Save the response helper

Save this module as nano_banana_save.py. The Python examples import it, and after a cURL request you run it on the saved response. It finds every image in a chat completions or generateContent response, restores missing Base64 padding, and names each file by its real format:

"""Save the images in a Nano Banana response from chat completions or generateContent."""
import base64
import json
import re
import sys
from pathlib import Path

DATA_URL = re.compile(r"data:image/[\w.+-]+;base64,([A-Za-z0-9+/=]+)")


def _extension(raw):
    if raw.startswith(b"\x89PNG"):
        return "png"
    if raw.startswith(b"\xff\xd8\xff"):
        return "jpg"
    if raw[:4] == b"RIFF" and raw[8:12] == b"WEBP":
        return "webp"
    return "bin"


def save_images(body, stem):
    """Write each image in a response body to stem.png, stem-2.png, and so on."""
    if body.get("error"):
        raise RuntimeError(f"API error: {body['error']}")
    if "choices" in body:  # chat completions: data URLs inside message.content
        text = body["choices"][0]["message"].get("content") or ""
        found = DATA_URL.findall(text)
        detail = text[:300]
    else:  # generateContent: inlineData parts; thought parts are not final output
        parts = [
            part
            for candidate in body.get("candidates") or []
            for part in (candidate.get("content") or {}).get("parts") or []
            if not part.get("thought")
        ]
        blobs = [part.get("inlineData") or part.get("inline_data") for part in parts]
        found = [blob["data"] for blob in blobs if blob]
        detail = body.get("promptFeedback") or [c.get("finishReason") for c in body.get("candidates") or []]
    if not found:
        raise RuntimeError(f"No image returned: {detail!r}")
    saved = []
    for number, encoded in enumerate(found, start=1):
        encoded = "".join(encoded.split())
        raw = base64.b64decode(encoded + "=" * (-len(encoded) % 4))
        suffix = "" if number == 1 else f"-{number}"
        path = Path(f"{stem}{suffix}.{_extension(raw)}")
        path.write_bytes(raw)
        saved.append(path)
    return saved


if __name__ == "__main__":
    # After a cURL request: python nano_banana_save.py response.json output-name
    response_body = json.loads(Path(sys.argv[1]).read_text(encoding="utf-8"))
    for saved_path in save_images(response_body, sys.argv[2]):
        print("Saved", saved_path)

​

Edit an image

"""Edit or combine images with Nano Banana Standard (gemini-2.5-flash-image)."""
import argparse
import base64
import os
import sys
from pathlib import Path

from openai import OpenAI

from nano_banana_save import save_images

MIME_TYPES = {".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp"}

parser = argparse.ArgumentParser(description="Edit one image, or combine up to three.")
parser.add_argument("prompt", help="the edit instruction")
parser.add_argument("images", nargs="+", help="local PNG, JPEG, or WebP files, or public HTTPS URLs")
parser.add_argument("--out", default="nano-banana-edit", help="output file name without extension")
args = parser.parse_args()
if len(args.images) > 3:
    sys.exit("gemini-2.5-flash-image works best with up to 3 input images.")

content = [{"type": "text", "text": args.prompt}]
for source in args.images:
    if source.startswith("https://"):
        url = source  # a public image URL is sent as is
    else:
        mime = MIME_TYPES.get(Path(source).suffix.lower())
        if mime is None:
            sys.exit(f"Use a PNG, JPEG, or WebP file: {source}")
        url = f"data:{mime};base64," + base64.b64encode(Path(source).read_bytes()).decode("ascii")
    content.append({"type": "image_url", "image_url": {"url": url}})

# max_retries=0: an automatic retry after a timeout could generate and bill the image twice
client = OpenAI(api_key=os.environ["LAOZHANG_API_KEY"], base_url="https://api.laozhang.ai/v1", timeout=300, max_retries=0)
reply = client.chat.completions.create(
    model="gemini-2.5-flash-image",
    messages=[{"role": "user", "content": content}],
)
for path in save_images(reply.model_dump(), args.out):
    print("Saved", path)

python nano_banana_edit.py "Replace the background with a plain light-gray studio wall. Keep the product, its label, and its shadow unchanged." product.jpg --out product-studio

base64 < product.jpg | tr -d '\n' > product.b64
jq -n --rawfile image product.b64 '{
  model: "gemini-2.5-flash-image",
  stream: false,
  messages: [{
    role: "user",
    content: [
      {type: "text", text: "Replace the background with a plain light-gray studio wall. Keep the product, its label, and its shadow unchanged."},
      {type: "image_url", image_url: {url: ("data:image/jpeg;base64," + $image)}}
    ]
  }]
}' > 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 @edit-request.json \
  -o edit-response.json

python nano_banana_save.py edit-response.json product-studio

​

Combine two or three images

python nano_banana_edit.py "Place the cat from the first image on the sofa in the second image. Match the room's lighting and keep the sofa unchanged." cat.png sofa.jpg --out cat-on-sofa

​

Send an image by URL

python nano_banana_edit.py "Add a rainbow over the hills. Keep everything else unchanged." https://example.com/images/hills.jpg --out hills-rainbow

​

Set the aspect ratio

• Standard outputs about 1K at every ratio, so leave out imageSize.
• Without aspectRatio, Google’s documented default is to match the output to the input image’s size.

base64 < street.jpg | tr -d '\n' > street.b64
jq -n --rawfile image street.b64 '{
  contents: [{
    role: "user",
    parts: [
      {text: "Turn this daytime street photo into a rainy night scene with neon reflections. Keep the buildings unchanged."},
      {inlineData: {mimeType: "image/jpeg", data: $image}}
    ]
  }],
  generationConfig: {
    responseModalities: ["IMAGE"],
    imageConfig: {aspectRatio: "16:9"}
  }
}' > native-edit-request.json

curl --fail-with-body --max-time 300 \
  "https://api.laozhang.ai/v1beta/models/gemini-2.5-flash-image:generateContent" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @native-edit-request.json \
  -o native-edit-response.json

python nano_banana_save.py native-edit-response.json street-night

"""Edit an image with Nano Banana Standard on the Gemini-native route and set the aspect ratio."""
import base64
import os
import sys
from pathlib import Path

import requests

from nano_banana_save import save_images

image = base64.b64encode(Path("street.jpg").read_bytes()).decode("ascii")
response = requests.post(
    "https://api.laozhang.ai/v1beta/models/gemini-2.5-flash-image:generateContent",
    headers={"Authorization": f"Bearer {os.environ['LAOZHANG_API_KEY']}"},
    json={
        "contents": [{
            "role": "user",
            "parts": [
                {"text": "Turn this daytime street photo into a rainy night scene with neon reflections. "
                         "Keep the buildings unchanged."},
                {"inlineData": {"mimeType": "image/jpeg", "data": image}},
            ],
        }],
        "generationConfig": {"responseModalities": ["IMAGE"], "imageConfig": {"aspectRatio": "16:9"}},
    },
    timeout=300,
)
if response.status_code != 200:
    sys.exit(f"HTTP {response.status_code}: {response.text[:500]}")
for path in save_images(response.json(), "street-night"):
    print("Saved", path)

​

Handle the response

• Chat completions: the image is inside the text of choices[0].message.content, usually as a Markdown image such as ![image](data:image/png;base64,iVBORw0...). Read the format from the data URL instead of assuming PNG, strip the data:image/...;base64, prefix before decoding, and add = padding when the length isn’t a multiple of 4.
• generateContent: each image is an inlineData part in candidates[].content.parts[], with mimeType and Base64 data.
  • A part marked thought: true isn’t final output, so skip it.
• No image: the reply holds only text, or no part has inlineData.
  • In native responses, check each candidate’s finishReason, and promptFeedback if present.
  • Example values include IMAGE_SAFETY, IMAGE_PROHIBITED_CONTENT, and NO_IMAGE.

​

Write clear edit instructions

• Name what should change and what must stay the same, for example: “Change only the blue sofa to a brown leather sofa. Keep the pillows, the rest of the room, and the lighting unchanged.” There is no mask parameter; Google calls this approach semantic masking.
• In a composite, refer to each image by its order and role, such as “the dress from the first image” and “the woman in the second image”.
• To protect a face or a logo, describe it in detail and say that it must not change.
• Describe the style, lighting, or placement you want instead of words like “better” or “nicer”.
• Make one change per request when precision matters. For a multi-step edit, send the saved result as the input of the next request.

​

Errors and billing

• HTTP 401: check the API key and the Authorization: Bearer header. Use an API key from Token management, not an account AccessToken.
• HTTP 400: check the model ID, the JSON body, and the aspectRatio value. Don’t send imageSize to Standard.
• HTTP 429, 5xx, or a timeout: retry with exponential backoff. After a timeout, find the request in call logs before sending it again, so you don’t pay twice for the same edit.
• Large photos: Base64 makes a file about a third larger, so downscale very large images before you encode them.

​

Migrate to Nano Banana 2

- "model": "gemini-2.5-flash-image"
+ "model": "gemini-3.1-flash-image"

• Each call costs $0.055 (public pricing as of September 24, 2026).
• An edit can use up to 14 references: at most 10 object images and 4 character images.
• On the Gemini-native route you can choose from 14 aspect ratios and add imageSize with one of these values:
  • 512, 1K, 2K, or 4K
• Results can differ for the same prompt, so run a sample of your usual edits before moving production traffic.

​

FAQ

​

Can I still call gemini-2.5-flash-image after October 2, 2026?

• LaoZhang API doesn’t guarantee how long the model stays available; it can stop at any time.
• Once it stops, requests fail. Unlike the -preview IDs, it isn’t mapped to another model, so requests won’t move to a newer model on their own.

​

Can a Standard edit return 2K or 4K images?

​

Can I still use gemini-2.5-flash-image-preview?

​

Related pages and sources

• Nano Banana overview — compare the five models, the two request formats, and billing rules
• Nano Banana 2 — the migration target, with up to 14 references and 512px to 4K output
• Nano Banana 2 Lite — low-cost 1K generation and single-image edits
• Nano Banana Pro image editing — multi-image edits with up to 14 references and 4K output
• Call logs — find a request’s status and charge
• Google: Nano Banana image generation — editing prompts, input limits, and model guidance
• Google: Gemini API deprecations — the shutdown date for gemini-2.5-flash-image
• Google: generateContent reference — imageConfig fields