Nano Banana Pro API: image editing

​

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 Pro has only a per-call price, and a Usage-based (按量计费) key can’t call it; the billing rules explain when a request is charged.

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

3

Add a save function for cURL

The cURL examples need jq. Define this shell function to save the last image in a Gemini-native response, which is the final result if interim images come back too, with the extension that matches its mimeType:

save_image() {
  local image='[.candidates[]?.content.parts[]? | select(.inlineData and (.thought | not))][-1].inlineData'
  local ext
  case "$(jq -r "$image.mimeType" "$1")" in
    image/png) ext=png ;;
    image/jpeg) ext=jpg ;;
    image/webp) ext=webp ;;
    *) jq '{error, promptFeedback, finishReasons: [.candidates[]?.finishReason]}' "$1"; return 1 ;;
  esac
  jq -r "$image.data" "$1" | base64 --decode > "$2.$ext" && echo "Saved $2.$ext"
}

When the response holds no image, the function prints the error, promptFeedback, and finishReason fields instead.

​

Edit a local image

"""Edit or combine images with Nano Banana Pro (gemini-3-pro-image) on the Gemini-native route."""
import argparse
import base64
import os
import sys
from pathlib import Path

import requests

URL = "https://api.laozhang.ai/v1beta/models/gemini-3-pro-image:generateContent"
RATIOS = ["1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "21:9"]
MIME_TYPES = {".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp"}
EXTENSIONS = {"image/png": "png", "image/jpeg": "jpg", "image/webp": "webp"}

parser = argparse.ArgumentParser(description="Edit one image, or combine up to 14 references.")
parser.add_argument("prompt", help="the edit instruction")
parser.add_argument("images", nargs="+", help="1 to 14 local PNG, JPEG, or WebP files")
parser.add_argument("--ratio", choices=RATIOS, help="output aspect ratio; omit to follow the input image")
parser.add_argument("--size", default="1K", choices=["1K", "2K", "4K"])
parser.add_argument("--out", default="pro-edit", help="output file name without extension")
args = parser.parse_args()
if len(args.images) > 14:
    sys.exit("Send at most 14 reference images.")

parts = [{"text": args.prompt}]
for path in args.images:
    mime = MIME_TYPES.get(Path(path).suffix.lower())
    if mime is None:
        sys.exit(f"Use a PNG, JPEG, or WebP file: {path}")
    data = base64.b64encode(Path(path).read_bytes()).decode("ascii")
    parts.append({"inlineData": {"mimeType": mime, "data": data}})

image_config = {"imageSize": args.size}
if args.ratio:
    image_config["aspectRatio"] = args.ratio

response = requests.post(
    URL,
    headers={"Authorization": f"Bearer {os.environ['LAOZHANG_API_KEY']}"},
    json={
        "contents": [{"role": "user", "parts": parts}],
        "generationConfig": {"responseModalities": ["IMAGE"], "imageConfig": image_config},
    },
    timeout=300,
)
if response.status_code != 200:
    sys.exit(f"HTTP {response.status_code}: {response.text[:500]}")

result = response.json()
images = [
    part["inlineData"]
    for candidate in result.get("candidates") or []
    for part in (candidate.get("content") or {}).get("parts") or []
    if "inlineData" in part and not part.get("thought")
]
if not images:
    reasons = [candidate.get("finishReason") for candidate in result.get("candidates") or []]
    sys.exit(f"No image returned: {result.get('promptFeedback') or reasons}")
for number, image in enumerate(images, start=1):
    suffix = "" if number == 1 else f"-{number}"
    output = Path(f"{args.out}{suffix}.{EXTENSIONS.get(image['mimeType'], 'bin')}")
    output.write_bytes(base64.b64decode(image["data"]))
    print("Saved", output)

python nano_banana_pro_edit.py "Add a small blue wizard hat on the cat. Keep the pose, fur, and background unchanged." cat.jpg --size 2K --out pro-cat-hat

base64 < cat.jpg | tr -d '\n' > cat.b64
jq -n --rawfile image cat.b64 '{
  contents: [{
    role: "user",
    parts: [
      {text: "Add a small blue wizard hat on the cat. Keep the pose, fur, and background unchanged."},
      {inlineData: {mimeType: "image/jpeg", data: $image}}
    ]
  }],
  generationConfig: {
    responseModalities: ["IMAGE"],
    imageConfig: {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-response.json

save_image pro-edit-response.json pro-cat-hat

​

Combine reference images

python nano_banana_pro_edit.py "Dress the person in the first image in the jacket from the second image, standing in the street from the third image. Keep the person's face and hairstyle unchanged." person.jpg jacket.png street.jpg --ratio 3:4 --size 2K --out pro-outfit

• 6 object images that must appear in the result with high fidelity, such as products or props
• 5 character images that keep people consistent across a series
• 3 style images that set the look, such as a palette or brushwork

​

Edit an image from a public 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": [
        {"text": "Add warm evening light through the window. Keep the furniture and layout unchanged."},
        {"fileData": {"fileUri": "https://example.com/images/living-room.png", "mimeType": "image/png"}}
      ]
    }],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {"aspectRatio": "3:2", "imageSize": "2K"}
    }
  }' \
  -o pro-url-edit-response.json

save_image pro-url-edit-response.json pro-living-room

• Use a URL once the request would pass 20 MB. Keep the whole request body under 20 MB; images sent as inlineData should total about 15 MB or less, so pass larger ones in fileData or downscale them first.
• The site’s robots.txt must not block crawlers from the image’s path, and a signed URL should stay valid for at least 30 minutes to cover queueing and retries.
• fileData and inlineData parts can share one parts array, in reference order. The full conditions are in Large images and image URLs.

​

Use the OpenAI-compatible route

"""Edit or combine images with Nano Banana Pro over the OpenAI-compatible route."""
import argparse
import base64
import os
import re
import sys
from pathlib import Path

from openai import OpenAI

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

parser = argparse.ArgumentParser(description="Edit one image, or combine several, over chat completions.")
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="pro-chat-edit", help="output file name without extension")
args = parser.parse_args()

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-3-pro-image",
    messages=[{"role": "user", "content": content}],
)
text = reply.choices[0].message.content or ""

found = re.findall(r"data:image/(png|jpe?g|webp);base64,([A-Za-z0-9+/=]+)", text)
if not found:
    sys.exit(f"No image returned: {text[:300]}")
for number, (kind, encoded) in enumerate(found, start=1):
    suffix = "" if number == 1 else f"-{number}"
    output = Path(f"{args.out}{suffix}.{EXTENSIONS[kind]}")
    output.write_bytes(base64.b64decode(encoded + "=" * (-len(encoded) % 4)))
    print("Saved", output)

python nano_banana_pro_chat_edit.py "Apply the color palette and brushwork of the first image to the scene in the second image." style.jpg photo.jpg --out pro-chat-restyle

​

Handle the response

• Gemini-native: each image is an inlineData part in candidates[].content.parts[], with mimeType and Base64 data.
  • Skip any part marked thought: true. Pro thinks before it renders, and a complex edit can return interim images along with the result; the last image is the final one.
  • Save the file with the extension that matches mimeType.
• Chat completions: the image is a data URL such as data:image/png;base64,... inside the text of choices[0].message.content. Take the format from the prefix, strip the prefix, and add = padding before decoding if the length isn’t a multiple of 4.
• No image: check each candidate’s finishReason, and promptFeedback if present, in native responses, or the reply text in chat responses. Common reasons are a safety block or an instruction the model answered with text only.

​

Prompt tips for edits

• Say what must stay unchanged, such as a face, a product label, or the layout. There is no mask parameter, so describe the area to change in words.
• Refer to each image by its order and role, such as “the jacket in the second image”.
• To keep a face or a logo intact, describe it in detail and say that it must not change.
• For text inside the image, put the exact words in quotes and name the font style.
• Split a complex edit into steps, and send each saved result as the input of the next request.

​

Errors and billing

• A request can return HTTP 200 without an image, for example when a safety check blocks the output. Edits are billed like generations, so the call is charged. Check finishReason (and promptFeedback if present), then change the instruction or reference images before resending; see Avoid paying for empty responses.
• HTTP 401 means the key or the Authorization: Bearer header is wrong; the Gemini-native route also accepts the key in x-goog-api-key. Retry 429 and 5xx responses with backoff, and check call logs before resending a request that timed out.
• If a fileData URL can’t be fetched, check that it loads without a login and that robots.txt allows it, or send the image as inlineData instead.
• HTTP 413 means the request body is too large. Pass large images by URL, or downscale them so the whole request stays under 20 MB.
• Base64 makes a file about a third larger, so downscale very large photos before you encode them.

​

FAQ

​

Can I edit with /v1/images/edits?

​

Can I edit only one area of an image?

​

What shape is the result when I leave out aspectRatio?

​

Related pages and sources

• Nano Banana Pro image generation — text-to-image, output sizes by ratio, and Google Search grounding
• Nano Banana 2 — lower-cost generation and editing up to 4K
• Nano Banana overview — compare the five models, the two request formats, and billing rules
• Nano Banana image editing (Standard) — edits with gemini-2.5-flash-image and its migration path
• Call logs — check a request’s status and charge
• Google: Nano Banana image generation — editing prompts, reference limits, and thinking
• Google: generateContent reference — imageConfig fields
• Google: file input methods — inline data and public URL inputs