Nano Banana Series Developer Guide

A one-stop guide to model selection, billing, endpoints, development formats, and FAQs for the Nano Banana series (Pro / 2 / 2 Lite / Gen 1), helping developers get started with the Gemini image generation API.

Model Cards

Model	Official Model ID	Billing	Notes
Nano Banana Pro	gemini-3-pro-image	Fixed per-request $0.09/req (approx. ¥0.63; approx. ¥0.55 after top-up promotions)	Highest quality
Nano Banana 2.1	gemini-nano-banana-2.1	Per-request $0.045/req (recommended for 4K output); or dynamic token-based billing, 1K approx. $0.026, 4K approx. $0.062	New in Oct 2026; better quality and text rendering; no 512px
Nano Banana 2	gemini-3.1-flash-image	Per-request $0.055/req (recommended for 4K output); or dynamic token-based billing, 2K approx. $0.04	Best value
Nano Banana 2 Lite	gemini-3.1-flash-lite-image	Fixed per-request $0.025/req; or token-based billing approx. $0.018/req (40% of official price)	Fastest & cheapest, 1K only
Nano Banana (Gen 1)	gemini-2.5-flash-image	Fixed per-request $0.02/req	Cheapest

For a complete price comparison, per-request vs. token-based billing, and token selection advice, see Nano Banana Series Pricing.

Sample Results

Both images below were generated with Nano Banana 2 Lite (gemini-3.1-flash-lite-image), showing text-to-image and image-editing results. They represent this model and these prompts only, not a performance guarantee for the other models in the series.

Text-to-image · 16:9 street scene (prompt only: a rainy old-town alley after the rain, warm street lamps reflected in the wet flagstones, someone walking by with an umbrella, 16:9 framing): 8.3 s, aspectRatio: 16:9 takes effect, and the signs reading 老茶馆, 客栈 and 酒肆 are all legible.

Image editing · dusk relight plus signage (reference: a street-side café; prompt: shift the light to a warm dusk tone and add a Chinese sign reading 转角咖啡 above the storefront, keeping everything else unchanged): 19.3 s, the sign strokes are crisp and follow the wall’s perspective, and the shadows of the plants and bicycles warm up with the light.

Size Control

• Follow the source image ratio: simply omit aspectRatio; in multi-image editing scenarios, the size of the last image takes precedence
• Resolution imageSize: supports 1K / 2K / 4K
  • Nano Banana (Gen 1) supports 1K only
  • Nano Banana 2 adds 512px
  • Nano Banana 2 Lite supports 1K only (no 2K/4K/512px)

When using the same code to call the first-gen gemini-2.5-flash-image, you must remove the imageSize parameter (it does not support 2K / 4K), otherwise the call will fail.

How to Integrate

Official Documentation

• Google official docs: ai.google.dev/gemini-api/docs/image-generation
• To integrate with APIYI, just replace the request URL + KEY with APIYI’s; all other parameters are identical to the official ones

Checking Official Status (diagnosing upstream issues)

The Nano Banana series runs on top of Google’s AIStudio / Gemini API. In rare cases, blurry or failing 2K / 4K output can be a problem on Google’s side rather than the integration layer — you can check Google’s official status page (copy and visit it yourself): aistudio.google.com/status.

For example, on Jun 19, 2026 that page reported “Issues with Nano Banana”: Nano Banana 2 / Pro on the Gemini API and AI Studio had problems at 2K or 4K resolution. When you see similar symptoms, compare against the official status page first to quickly tell whether it’s an upstream outage.

APIYI runs the Nano Banana series across dual AIStudio + Vertex channels for redundancy: when one official channel has issues, the other can take over to keep the service available.

Endpoint Support

• Recommended endpoint (Gemini native): https://api.apiyi.com/v1beta/models/gemini-3-pro-image:generateContent
• Supports calls via OpenAI-compatible mode (/v1/chat/completions; pass Base64 or a public link through image_url)
• Does not support /v1/image/generations

Development Format (Default Recommendation)

• [Recommended] Use the Google native endpoint format
• Images: upload as Base64, download and re-host
• Call method: synchronous multi-threaded calls; asynchronous calls are not yet supported

Input Image Requirements

• A single image cannot exceed 7MB (Google’s rule); if imported via Google Cloud Storage, the per-file limit is 30MB
• Up to 14 images per prompt
• Supported MIME types: image/png, image/jpeg, image/webp, image/heic, image/heif (the jpg format is already supported by APIYI)
• Base64 size inflation: converting an image to Base64 increases its size by about 33.3% (a 7MB image becomes about 9.3MB)
• APIYI limit: the total volume of images uploaded in a single request must be under 100MB — all calls are synchronous, and oversized payloads can cause memory blowup

Google official technical specs: inline / console upload per-file limit is 7MB, supporting png/jpeg/webp/heic/heif

Base64 encoding increases size by about 33.3%: a 7MB image is roughly equal to 9.3MB

Best practice: apply lossless compression to images before sending them to the API, to avoid oversized resolutions slowing down requests.

Google official spec reference (please copy and visit it yourself): docs.cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/3-pro-image

URL Image Input

In addition to Base64, the Gemini native endpoint accepts an image URL directly through fileData.fileUri. This keeps the request body small and saves you from downloading and encoding the image yourself.

With URL input, Google’s servers download the image, not APIYI. Whether it works, and how fast, depends on how easily Google can reach your image host, not on whether the link opens in your own browser. The requirements and troubleshooting steps below come from real support tickets and our own tests (2026-10-16, NB2 / Pro, three routes).

Prefer Base64 (inlineData) whenever you can. You download the image yourself and put it in the request body, so nothing depends on Google fetching it. This is the most reliable option. URL input suits images that already live on a global CDN outside mainland China when you want to keep requests small.

What Makes a Usable Link

Requirement	Details
Points directly to an image file	Not a cloud-drive share page or an image preview page. If it points to a web page, Google reads the whole page and returns a 400 The input token count exceeds the maximum number of tokens allowed within seconds
Publicly readable without credentials	No login, cookies, or Referer checks. In our tests, private buckets and links without access returned a 400 fetch failure after about 60 seconds
Fast for Google’s servers	Google allows about 60 seconds to fetch a URL. Hosts served only through a mainland China CDN (such as Tencent Cloud COS with default settings) are often unreachable, and overseas object storage can also be slow: on one AWS S3 US West bucket, more than half of fetches for a roughly 500KB image timed out at 60 seconds
Signed links stay valid for the whole request	Don’t give presigned or temporary URLs a very short lifetime or a download limit
Original direct link without image-processing parameters	Parameters such as ?x-oss-process=... cause a format mismatch. See MIME type mismatch
7MB or less per image	Same limit as Base64. See Input Image Requirements above

Both http:// and https:// links worked in our tests. gs:// (Google Cloud Storage) can only be read by some routes, so we don’t recommend it through APIYI.

Request Format

{
  "contents": [{
    "role": "user",
    "parts": [
      { "fileData": { "fileUri": "https://your-cdn.example.com/a.png", "mimeType": "image/png" } },
      { "fileData": { "fileUri": "https://your-cdn.example.com/b.jpg", "mimeType": "image/jpeg" } },
      { "text": "Put the jacket from the second image on the person in the first image" }
    ]
  }],
  "generationConfig": {
    "responseModalities": ["IMAGE"],
    "imageConfig": { "imageSize": "2K" }
  }
}

• Multiple images: one fileData per image, in order inside parts. You can also mix them with inlineData; in our tests, two URL images plus one Base64 image in a single request generated normally
• mimeType: set it to the image’s real format. In our tests, current routes still read the image when it was wrong or missing, but don’t rely on that
• Field names: use camelCase fileData / fileUri / mimeType, matching Google’s official docs. The snake_case forms file_data / file_uri are currently accepted as well

Confirm the Reference Image Was Actually Read

Some routes don’t return an error when the fetch fails: they return 200, generate an image and bill as usual, but the result ignores your image entirely. So don’t rely on the status code alone. Check usageMetadata.promptTokensDetails in the response:

"promptTokensDetails": [
  { "modality": "TEXT", "tokenCount": 17 },
  { "modality": "IMAGE", "tokenCount": 1120 }
]

An IMAGE entry means the image was read (with default settings we measured about 1120 tokens per image on Nano Banana 2 and about 560 on Pro). If there is only TEXT, Google did not get the image, and the result will not reference it. The Python example below includes this check.

How Fetch Failures Show Up

Symptom	Cause	Billed
200 with an image that ignores the reference; promptTokensDetails has only TEXT	The link returned 404 or similar, and some routes silently skip the image	Yes
400 within seconds: Cannot fetch content from the provided URL ... Status: URL_ERROR-ERROR_NOT_FOUND	The link returned 404, and other routes report it directly	No
400 after about 60 seconds: Cannot fetch content from the provided URL with Status URL_REJECTED-REJECTED_FC_TIMEOUT or URL_REJECTED-REJECTED_SCHEDULE_TIME_OVER_DEADLINE, or The request to crawl the page timed out	Google’s download timed out: the host is too slow for Google, or the link is not accessible	No
400 within seconds: The input token count exceeds the maximum number of tokens allowed	The link points to a web page, not an image file	No

A retry of the same link getting faster does not mean the problem is solved. Google caches images it has fetched, so a second request for the same URL often hits the cache, while a newly uploaded image will time out again. When testing, add a random query parameter (such as ?v=<random>) to bypass the cache and measure the real fetch speed.

For a full timeout case study, see Image Edit Returns Unable to Process Input Image?, which also covers the empty-Base64 error that is often confused with it.

Curl Example (fileUri)

curl --location 'https://api.apiyi.com/v1beta/models/gemini-3-pro-image:generateContent' \
  --header "Authorization: Bearer $APIYI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
      "contents": [{
          "role": "user",
          "parts": [
              {
                  "fileData": {
                      "fileUri": "https://raw.githubusercontent.com/apiyi-api/ai-api-code-samples/refs/heads/main/Vision-API-OpenAI/otter.png",
                      "mimeType": "image/png"
                  }
              },
              { "text": "add five dogs" }
          ]
      }],
      "generationConfig": {
          "responseModalities": ["IMAGE"],
          "imageConfig": { "aspectRatio": "16:9", "imageSize": "2K" }
      }
  }' > output.json

Python Example (fileUri)

import base64, os, requests

API_KEY = os.environ["APIYI_API_KEY"]
MODEL = "gemini-3.1-flash-image"
URL = f"https://api.apiyi.com/v1beta/models/{MODEL}:generateContent"

IMAGE_URLS = [
    "https://raw.githubusercontent.com/apiyi-api/ai-pics/refs/heads/main/1762260696217_dd0352c1f9604540.png",
]
PROMPT = "Change the person's clothes to a blue jacket and keep everything else the same"

payload = {
    "contents": [{
        "role": "user",
        "parts": [
            *[{"fileData": {"fileUri": u, "mimeType": "image/png"}} for u in IMAGE_URLS],
            {"text": PROMPT},
        ],
    }],
    "generationConfig": {
        "responseModalities": ["IMAGE"],
        "imageConfig": {"imageSize": "2K"},
    },
}

resp = requests.post(URL, json=payload, timeout=300,
                     headers={"Authorization": f"Bearer {API_KEY}"})
if resp.status_code != 200:
    raise SystemExit(f"HTTP {resp.status_code}: {resp.text[:500]}")
data = resp.json()

# 1. Confirm the reference image was read: promptTokensDetails must include IMAGE
details = data.get("usageMetadata", {}).get("promptTokensDetails", [])
image_tokens = sum(d.get("tokenCount", 0) for d in details if d.get("modality") == "IMAGE")
if image_tokens == 0:
    print("⚠️ Reference image was not read (Google could not fetch it); the result will ignore it")

# 2. Iterate over parts to find the image; never index into it
for part in data["candidates"][0]["content"]["parts"]:
    inline = part.get("inlineData")
    if inline:
        with open("output.png", "wb") as f:
            f.write(base64.b64decode(inline["data"]))
        print(f"✅ Saved output.png (reference image: {image_tokens} tokens)")
        break
else:
    print("No image in the response:", data["candidates"][0].get("finishReason"))

Can the OpenAI-Compatible Endpoint Take a URL?

Yes. Pass a public link as image_url on /v1/chat/completions; in our tests both Nano Banana 2 and Pro read the image and generated normally. The same link requirements apply. For multi-turn editing or precise resolution control, the native endpoint is still recommended.

Billing Basics (Important)

• Synchronous call duration: Pro / 2 at 4K take a reasonable generation time of approx. 30–150s
• Disconnecting on timeout still incurs charges: for example, if generation takes 120s but the client sets the timeout to 100s and disconnects, you are still charged
• 429 / 503 are not charged: failed requests are not billed (we try not to keep customers waiting or stuck without an image)
• Content-safety refusals still incur charges: when a customer’s input has content-safety issues and Google refuses to generate the image, a status code 200 is still charged — see error handling and the guarantee plan below

Google Search grounding is charged on top of the per-call price

Pro supports the googleSearch tool (grounding triggered in 3/3 test runs, returning full groundingMetadata), useful for weather cards, stock charts, and anything else that needs live information.

But the search call fee is added on top of the $0.09 per-call price, not included in it:

Scenario	Charge per call
Ordinary generation (no tools)	$0.09
With search, model ran 1 query	$0.09 + $0.014 = $0.104
With search, model ran 2 queries	$0.09 + $0.028 = $0.118

{
  "contents": [{ "parts": [{ "text": "A weather card poster for Tokyo today" }] }],
  "tools": [{ "googleSearch": {} }]
}

The model decides how many searches to run; you cannot set it in advance. In testing, a single image request issued 1–3 queries on its own, so once this tool is enabled the per-call cost becomes a range ($0.104–$0.132) rather than a fixed $0.09. Budget against the upper bound.

Image Search grounding (searchTypes.imageSearch) does not work on Pro — 0/2 runs triggered it, and imageSearchQueries never appeared in groundingMetadata. It is exclusive to Nano Banana 2 (gemini-3.1-flash-image); see Nano Banana 2 · Three parameters that affect billing.

thinkingLevel has no effect on Pro — don’t copy it over from NB2

generationConfig.thinkingConfig.thinkingLevel is exclusive to the Nano Banana 2 series. Passing high to Pro:

• Does not error — the request returns 200 normally
• But has no effect: measured thoughtsTokenCount ranged 108–156, fully overlapping the 130–159 range seen without the parameter
• Pro’s thinking is always on and cannot be tuned, as Google’s own documentation states

On top of that, Pro bills a flat rate per call, so thinking never reaches the invoice — tuning this parameter on Pro has neither an effect nor a cost rationale. To control thinking overhead, use Nano Banana 2’s metered billing instead.

Timeout Settings (Important)

4K image generation takes longer overall, involving stages such as image upload, API processing, and Base64 image download (our backend bills by API processing time). Under normal conditions, 4K takes about 50s (excluding polling), but if the client sets the timeout too short, it will disconnect prematurely before generation completes and report an error:

API Connection Error: HTTPSConnectionPool(host='api.apiyi.com', port=443): Read timed out. (read timeout=120)

Call logs: time-to-first-byte for 4K generation is about 43–61s, so the default 120s timeout is too tight

To be safer, we recommend setting the timeout by resolution:

timeout = {
    "1K": 300,  # 5 minutes - quick preview
    "2K": 300,  # 5 minutes - recommended
    "4K": 600,  # 10 minutes - ultra HD
}

Multi-turn conversational editing (native supports it; reverse models don’t)

The Nano Banana series uses the Gemini native format and supports true conversational multi-turn editing: append each turn’s generated image back into contents as a role: "model" inlineData, then send the next user instruction. The model edits based on the full conversation history and accumulates changes (e.g. recolor the sofa first, then add an accessory — the earlier change is preserved).

This differs fundamentally from “reverse” image models — be clear on it before integrating:

Aspect	Nano Banana (Gemini native)	Reverse model (e.g. gpt-image-2-all)
Endpoint	/v1beta/...:generateContent	/v1/chat/completions (chat-style)
Multi-turn mechanism	✅ True conversational: backfill role:model images into contents; the model reads history	❌ No conversation state: images in assistant history are ignored
Cross-turn accumulation	✅ Supported (red sofa → add hat, sofa stays red)	⚠️ Re-feed only, one-step edits
How to edit the previous image	Backfill the last output as a model image in the conversation history	Pass the previous image URL as the reference in a new user message

Tested: backfilling the previous image as a model-role turn lets Nano Banana 2 (gemini-3.1-flash-image) correctly keep editing and accumulate changes; a reverse model only reads the reference image from the last user message, so keeping conversation history does not work for multi-turn there.

Minimal example (backfill each output into the same contents):

import requests, base64

API_KEY = "sk-your-api-key"
URL = "https://api.apiyi.com/v1beta/models/gemini-3.1-flash-image:generateContent"
H = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}
CFG = {"responseModalities": ["IMAGE"], "imageConfig": {"imageSize": "2K"}}

contents = []  # keep one running conversation history

def turn(instruction, save_to):
    contents.append({"role": "user", "parts": [{"text": instruction}]})
    data = requests.post(URL, headers=H,
                         json={"contents": contents, "generationConfig": CFG}, timeout=300).json()
    part = next(p for p in data["candidates"][0]["content"]["parts"] if "inlineData" in p)
    contents.append({"role": "model", "parts": [part]})   # key: backfill the output image
    with open(save_to, "wb") as f:
        f.write(base64.b64decode(part["inlineData"]["data"]))

turn("Generate an orange cat sitting on a blue sofa, simple line-art style", "step1.png")
turn("Make the sofa red; keep the cat and composition unchanged", "step2.png")   # edits the previous image
turn("Put a small yellow hat on the cat; keep everything else the same", "step3.png")  # accumulates; red sofa kept

Full details (history-backfill vs re-feed styles, starting multi-turn from an existing image) are in Image Editing API · Multi-turn conversational editing.

Always Iterate parts to Get the Image — Never Index Into It

parts is a heterogeneous array: it may hold only an image segment, or interleave text and image segments, and neither the length nor the order is guaranteed. Hardcoded access like parts[0] / parts[1] is therefore certain to fail intermittently.

Three layouts have been observed in testing:

parts layout	Length	Image index
inlineData	1	0
text + inlineData	2	1
inlineData + text	2	0

A text segment can arise for more than one reason: including TEXT in responseModalities, or a prompt that asks the model to explain itself, both make the model return text alongside the image — and whether that text lands before or after the image is not fixed either. So the index the image sits at is not a constant, and the same code can receive different structures across requests.

The two hardcoded-index patterns are complementary: the image always lands on either [0] or [1], so whichever you pick, some requests will come back without an image for you. Flipping between [0] and [1] does not fix anything — only selecting by field shape is stable.

The correct approach is to select by field shape rather than by position. Note that you take the last inlineData, not the first — complex tasks return multiple images, and the last one is the final version (see the next section):

cand = (resp.get("candidates") or [{}])[0]
parts = (cand.get("content") or {}).get("parts") or []      # handles parts=null
images = [p["inlineData"] for p in parts if "inlineData" in p]
if not images:
    raise RuntimeError(f"No image returned, finishReason={cand.get('finishReason')}")

final = images[-1]                                 # last one is the final version
image_bytes = base64.b64decode(final["data"])
mime = final["mimeType"]                           # trust the response; don't hardcode image/png

const parts = resp?.candidates?.[0]?.content?.parts ?? [];
const images = parts.filter((p) => p.inlineData?.data);   // ✅ never write parts[1]
if (images.length === 0) throw new Error("Gemini returned no image data");
const { data, mimeType } = images[images.length - 1].inlineData;   // last is the final version

Hardening: declaring responseModalities: ["IMAGE"] in generationConfig states that you only want an image, which cuts down on extra text segments.

This is hardening, not a replacement — filtering still has to come first. The reverse does not hold: passing ["TEXT","IMAGE"] does not guarantee a text segment; the model may still return the image alone.

Do not hardcode mimeType either. The image format in the response is not constant — both image/png and image/jpeg occur. Writing files with a fixed .png extension produces files whose extension contradicts their contents — always let the response’s mimeType decide the extension.

Why Do Responses Occasionally Contain Multiple Images

When calling gemini-3-pro-image, you may occasionally see multiple image parts in a single response (2–10 observed in testing), matching sporadic 6000+ (even five-digit) output-token entries in your logs. This is not an anomaly: Google’s official docs state that Gemini 3 image models have “Thinking” enabled by default (it cannot be disabled in the API), the model generates interim images to test composition and logic, these drafts appear in parts alongside the final version, and “the last image within Thinking is also the final rendered image” (official docs: ai.google.dev/gemini-api/docs/image-generation). Based on our testing in July 2026 (Google native generateContent format):

Scenario	Images returned
Pure text-to-image	Always 1 (even if the prompt explicitly asks for “multiple images”)
Simple image editing (add accessories / change background / restyle)	Always 1
Complex task-style editing (e.g. “4-view character sheet + outfit change + white background” with multiple constraints)	2–10, consistently reproducible

The trigger is the task complexity of the prompt, not “image editing” itself. The multiple images still live in a single candidate (not multiple candidates), and each one is a complete image — they are the thinking process’s successive drafts of the same design (same composition, slightly different details), and the last part is the final version. These drafts come back as ordinary image parts (with a thoughtSignature field, without a thought: true flag); Google’s docs say Thinking generates at most two interim images, but we observed up to 10 on complex tasks.

Billing impact: each image is billed at a fixed token count (1120 tokens per image at 1K/2K resolution, 2000 at 4K), so output tokens grow strictly linearly with the number of images. A sporadic 6000+ (up to ~13.5k in extreme cases) output-token entry in your logs is simply a 4–10 image response, not a billing anomaly.

Recommended downstream code:

parts = response["candidates"][0]["content"]["parts"] or []   # parts is null on safety refusals
images = [p["inlineData"]["data"] for p in parts if "inlineData" in p]

if images:
    final_image = images[-1]   # last one = final version

• Always iterate over parts — do not assume one image per response; any per-image counting or saving logic must go by the actual number of parts
• Take the last image when you only need one: the earlier drafts have unfinished details and slightly lower quality, so avoid taking the first
• Controlling the image count via the prompt is largely ineffective (in testing, “output only one image” instructions were ignored) — handle it in code
• Multi-image responses take 35–142s (at 1K resolution, longer with more images), noticeably longer than single-image ones — keep the timeout recommendations above (≥ 5 minutes)

For the full breakdown of usageMetadata fields (the gap between details and totals, the counting quirk on refusal responses, and more), see Usage Fields & Output Explained.

FAQs

Error Handling Guide

The three key indicators for diagnosing failed generations, content moderation policies, and friendly prompt strategies

Must-Read Common Dev Questions

Troubleshooting failed generations and common questions

Failed Generation Guarantee Plan

For failures not caused by your input, credits are reimbursed per the number of failed requests

Why do I get connection reset by peer / write_response_body_failed (500)?

The full error looks like:

[&{{write tcp ip:port->ip:port: write: connection reset by peer Unknown error shell_api_error  write_response_body_failed} 500 }]

This is usually caused by oversized image uploads — the request body gets too large and the connection collapses. Follow these best practices:

• Limit the image count: stay within the official rules (max 14 images per prompt — see the official spec above).
• Limit per-image size: keep each image under 5MB — the official per-image cap is 7MB, and base64 encoding inflates size by roughly 1/3, so leave headroom.
• Compress on the frontend before uploading: compress images on the frontend (or a server-side relay) before sending them to the API — common practice is capping the longest edge, converting to JPEG/WebP, and tuning the quality parameter.
• Switch to URL input: the Gemini native format supports passing an image URL via fileData.fileUri, sidestepping oversized base64 request bodies entirely — see URL Image Input above.

Use Cases

• AI chat clients: clients such as Cherry Studio can be configured to generate images directly via APIYI
• Generation testing: quickly verify model performance in a chat client or the console

Advanced Needs

• Want to upload images via URL? Use fileData.fileUri on the Gemini native endpoint or image_url on the OpenAI-compatible endpoint. Google’s servers download the image, so the host matters. See the link requirements, how to detect fetch failures, and code examples in URL Image Input above.
• Want to get a download URL directly (instead of Base64)? Use the NB-OSS group — see Nano Banana OSS Group.