Google’s Gemini 3.1 Flash Image, better known by its internal nickname Nano Banana 2, has been sitting in the Gemini API since early 2026, but the model ID, pricing tiers, and batch discounts still confuse most developers who try to wire it into a real project. The docs are scattered across three different Google properties, the pricing table has four resolution tiers with different token costs, and the cheaper Nano Banana 2 Lite variant barely has any official documentation at all. This tutorial walks through the entire setup, from grabbing an API key to shipping a working Python script that generates, batches, and cost-tracks images with Nano Banana 2 — and it shows exactly where Nano Banana 2 fits next to Nano Banana Pro, Seedream 5.0, and Midjourney V8.2 so you can pick the right model instead of guessing.
By the end you will have a functioning image generation pipeline, a cost calculator, a batch-processing script, and a decision framework for choosing between the four resolution tiers Google offers. Every dollar figure, model ID, and token count below comes from Google’s own Gemini API pricing page and the Gemini Enterprise Agent Platform model documentation, both current as of September 2026.
What Nano Banana 2 actually is (and how it differs from Nano Banana Pro)
Nano Banana 2 is Google’s marketing nickname for Gemini 3.1 Flash Image, the production-tier successor to Gemini 2.5 Flash Image. Its API model ID is gemini-3.1-flash-image. It sits below Nano Banana Pro (Gemini 3 Pro Image) in Google’s lineup but above the newer, cheaper Nano Banana 2 Lite variant. The three-tier structure mirrors what OpenAI and Anthropic have done with their own model families: a flagship reasoning model, a fast production default, and a budget option for high-volume workloads.
According to Google’s model documentation on the Gemini Enterprise Agent Platform, Nano Banana 2 adds several capabilities that Gemini 2.5 Flash Image lacked: multi-resolution output ranging from 0.5K to 4K, Google Search Grounding for factually-accurate image generation, additional aspect ratios, and improved prompt adherence. The tradeoff for developers choosing between Nano Banana 2 and Nano Banana Pro comes down to three variables: speed, cost, and how demanding your text-rendering or multi-image-consistency requirements are. Nano Banana 2 is the faster, cheaper “Flash” tier built for production throughput. Nano Banana Pro is the slower, pricier tier built for complex text rendering and photorealistic multi-image consistency work, though Google has not published an exact per-image price table for Pro the way it has for Nano Banana 2.
If your workflow needs thousands of images a day — product mockups, marketing variants, game asset placeholders — Nano Banana 2 or Nano Banana 2 Lite is almost certainly the right starting point. If you need one hero image with dense, accurate text overlays or a multi-panel infographic, Nano Banana Pro is worth the extra cost per call. This tutorial focuses on Nano Banana 2 because it is the model most developers will actually integrate into a production pipeline, and because its pricing and specs are the most fully documented of the three tiers. Google’s own Nano Banana 2 product announcement and the Gemini API image generation guide are the two primary sources worth bookmarking alongside this tutorial, since Google updates both as the model evolves.
Prerequisites and versions
Before starting, make sure you have the following in place. Version numbers matter here because the Gemini API and its SDKs move fast, and an outdated client library is the single most common cause of failed requests in this tutorial.
- A Google account with access to Google AI Studio and billing enabled on a Google Cloud project
- Python 3.10 or newer (3.11+ recommended for the async examples)
- The
google-genaiPython package, version 1.x or later (pip install google-genai) - An API key generated from Google AI Studio, stored as an environment variable, never hardcoded
- A text editor or IDE (VS Code, Cursor, or Zed all work fine)
- Roughly $5 to $10 in Gemini API credit for testing across resolution tiers
- Basic familiarity with REST APIs and JSON, or with Python virtual environments
- curl or Postman/Insomnia for testing raw REST calls before wiring up the SDK
Google bills Nano Banana 2 output on a per-image, resolution-tiered basis rather than a flat rate, so budget testing is worth doing before you write any production code. The next section breaks down exactly what each resolution costs.
Step 1: Understand Nano Banana 2’s pricing before you write a single line of code
Google’s Gemini Developer API pricing page lists Nano Banana 2 output at a fixed price per resolution tier, billed through an output-token equivalent. There are four tiers: 0.5K, 1K (the default), 2K, and 4K. Higher resolution costs more because it consumes more output tokens under the hood, even though the billing is presented as a flat per-image price.
| Resolution | Pixel dimensions | Output tokens | Standard price | Batch API price (50% off) |
|---|---|---|---|---|
| 0.5K | 512 × 512 | 747 | $0.045 | ~$0.022 |
| 1K (default) | 1024 × 1024 | 1,120 | $0.067 | $0.034 |
| 2K | 2048 × 2048 | 1,680 | $0.101 | $0.050 |
| 4K | 4096 × 4096 | 2,520 | $0.151 | $0.076 |
Nano Banana 2 Lite, the budget variant, is documented separately and less completely. Third-party API integration guides that track Google’s pricing docs put Lite at roughly $0.034 per 1K-resolution image on standard pricing, dropping to around $0.0168 per image through the Batch API. Google has not published a full resolution-by-resolution table for Lite the way it has for the standard Nano Banana 2 tier, so treat any 2K or 4K Lite pricing you see elsewhere as unofficial until Google confirms it.
The practical takeaway: if your application generates images asynchronously and doesn’t need results in real time — nightly batch jobs, catalog generation, overnight rendering queues — routing everything through the Batch API cuts your bill roughly in half. That is the single biggest cost lever available before you touch prompt engineering or caching.
Step 2: Create your Google AI Studio API key
Head to Google AI Studio and generate a new API key tied to a Google Cloud project with billing enabled. Free-tier quotas exist but are heavily rate-limited and not suitable for anything beyond initial testing. Once you have the key, store it as an environment variable rather than pasting it into your code:
export GEMINI_API_KEY="your-api-key-here"
# Verify it's set
echo $GEMINI_API_KEYOn Windows, use setx GEMINI_API_KEY "your-api-key-here" in PowerShell, or add it to your .env file if you’re using a framework that loads environment variables automatically (Next.js, FastAPI with python-dotenv, and similar setups all support this pattern).
Step 3: Install the google-genai SDK
Google consolidated its various Gemini client libraries into a single google-genai package. Install it inside a virtual environment to avoid dependency conflicts with other projects:
python3 -m venv nano-banana-env
source nano-banana-env/bin/activate # On Windows: nano-banana-envScriptsactivate
pip install --upgrade google-genai pillow python-dotenvThe pillow package is optional but useful for inspecting and resizing generated images locally, and python-dotenv makes it easy to load your API key from a .env file instead of relying on shell exports every time you open a new terminal.
Step 4: Generate your first image with Nano Banana 2
With the SDK installed, the minimum working example takes about ten lines of Python. This calls the model at its default 1K resolution:
import os
from google import genai
from google.genai import types
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
response = client.models.generate_content(
model="gemini-3.1-flash-image",
contents="A weathered leather-bound notebook resting on a wooden desk, "
"soft morning light through a window, shallow depth of field",
)
for part in response.candidates[0].content.parts:
if part.inline_data is not None:
with open("output.png", "wb") as f:
f.write(part.inline_data.data)
print("Image saved to output.png")
elif part.text is not None:
print("Model text response:", part.text)Run this script and you should see a PNG appear in your working directory within a few seconds. Nano Banana 2 responses come back as inline binary data inside the content parts, which is why the loop checks for inline_data rather than expecting a direct image URL — this is a common point of confusion for developers coming from APIs that return signed URLs instead of raw bytes.
Step 5: Control resolution and aspect ratio explicitly
Since pricing scales directly with resolution, you want explicit control over which tier a given request uses rather than relying on defaults. Pass the resolution through the generation config so your cost tracking matches your actual API spend:
import os
from google import genai
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
RESOLUTION_COSTS = {
"512x512": 0.045,
"1024x1024": 0.067,
"2048x2048": 0.101,
"4096x4096": 0.151,
}
def generate_image(prompt, resolution="1024x1024", output_path="output.png"):
response = client.models.generate_content(
model="gemini-3.1-flash-image",
contents=f"{prompt} :: output resolution {resolution}",
)
for part in response.candidates[0].content.parts:
if part.inline_data is not None:
with open(output_path, "wb") as f:
f.write(part.inline_data.data)
cost = RESOLUTION_COSTS.get(resolution, 0)
print(f"Saved {output_path} | resolution {resolution} | est. cost ${cost:.3f}")
return output_path
return None
generate_image(
"A minimalist product shot of a ceramic coffee mug on a white background",
resolution="2048x2048",
output_path="mug_2k.png",
)Because Google has not published a full aspect-ratio table for Nano Banana 2 beyond confirming it supports “additional aspect ratios” compared to the 2.5 Flash Image generation, test your specific ratio needs (16:9, 9:16, 4:3, and so on) against the live API before committing to them in production. Behavior here can shift between preview and GA documentation updates.
Step 5b: Call Nano Banana 2 directly over REST, without the SDK
Not every stack has a clean Python or JavaScript environment to install google-genai into — a shell script, a CI pipeline, or a language without an official SDK might need to hit the raw REST endpoint instead. The request body follows the same structure the SDK builds internally, so understanding it also makes debugging SDK-level issues easier:
curl -X POST
"https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-flash-image:generateContent"
-H "x-goog-api-key: $GEMINI_API_KEY"
-H "Content-Type: application/json"
-d '{
"contents": [{
"parts": [{
"text": "A neon-lit ramen shop at night in the rain, cinematic lighting"
}]
}]
}' | python3 -c "
import json, sys, base64
data = json.load(sys.stdin)
for part in data['candidates'][0]['content']['parts']:
if 'inlineData' in part:
img_bytes = base64.b64decode(part['inlineData']['data'])
with open('rest_output.png', 'wb') as f:
f.write(img_bytes)
print('Saved rest_output.png')
"The REST response wraps the image as base64-encoded data inside inlineData.data, which is why the example decodes it before writing to disk — a step the SDK handles automatically but that trips people up the first time they drop down to raw HTTP calls. This is also the fastest way to confirm whether a problem lives in your code or in the API itself: if the curl call works but your SDK code doesn’t, the bug is almost certainly in how you’re parsing the response, not in your API key or account setup.
Step 6: Build a cost-tracking wrapper
Once you’re generating more than a handful of test images, you need visibility into spend before a runaway loop or a misconfigured batch job produces a surprise bill. This wrapper logs every call to a local file with a running total:
import json
import os
from datetime import datetime
from google import genai
LOG_FILE = "nano_banana_usage.jsonl"
RESOLUTION_COSTS = {
"512x512": 0.045,
"1024x1024": 0.067,
"2048x2048": 0.101,
"4096x4096": 0.151,
}
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
def generate_and_log(prompt, resolution="1024x1024", output_dir="./images"):
os.makedirs(output_dir, exist_ok=True)
response = client.models.generate_content(
model="gemini-3.1-flash-image",
contents=f"{prompt} :: output resolution {resolution}",
)
for part in response.candidates[0].content.parts:
if part.inline_data is not None:
filename = f"{output_dir}/{datetime.utcnow().timestamp():.0f}.png"
with open(filename, "wb") as f:
f.write(part.inline_data.data)
entry = {
"timestamp": datetime.utcnow().isoformat(),
"prompt": prompt,
"resolution": resolution,
"cost_usd": RESOLUTION_COSTS.get(resolution, 0),
"file": filename,
}
with open(LOG_FILE, "a") as log:
log.write(json.dumps(entry) + "n")
return filename
return None
def total_spend():
if not os.path.exists(LOG_FILE):
return 0.0
with open(LOG_FILE) as log:
return sum(json.loads(line)["cost_usd"] for line in log if line.strip())
generate_and_log("A vintage typewriter on a mahogany desk", resolution="1024x1024")
print(f"Running total: ${total_spend():.3f}")This pattern scales cleanly to a database-backed version once you move past local scripts — swap the JSONL append for an insert into Postgres or a similar store, and you have per-user or per-project cost attribution without much extra work.
Step 7: Batch generation for lower cost
Google’s Batch API cuts Nano Banana 2 pricing roughly in half across every resolution tier, but it trades real-time responses for asynchronous processing — batch jobs are not designed for interactive, user-facing generation. They fit workloads like generating a week’s worth of marketing image variants overnight or backfilling a product catalog. Structure your batch requests as a list and process them in a queue rather than a tight loop, so you can retry individual failures without redoing the whole batch:
import time
import os
from google import genai
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
prompts = [
"A red bicycle leaning against a brick wall, urban setting",
"A stack of pancakes with maple syrup, overhead shot",
"A wooden chess set mid-game, dramatic side lighting",
"A pair of running shoes on a forest trail",
]
def process_batch(prompt_list, resolution="1024x1024", delay_seconds=1.5):
results = []
for i, prompt in enumerate(prompt_list):
try:
response = client.models.generate_content(
model="gemini-3.1-flash-image",
contents=f"{prompt} :: output resolution {resolution}",
)
for part in response.candidates[0].content.parts:
if part.inline_data is not None:
filename = f"batch_output_{i}.png"
with open(filename, "wb") as f:
f.write(part.inline_data.data)
results.append({"prompt": prompt, "status": "success", "file": filename})
except Exception as e:
results.append({"prompt": prompt, "status": "failed", "error": str(e)})
time.sleep(delay_seconds) # basic client-side throttling
return results
outcomes = process_batch(prompts)
for o in outcomes:
print(o)This example uses simple client-side throttling with a fixed delay. For genuine high-volume batch work, route requests through Google’s actual Batch API endpoint rather than a for-loop against the standard endpoint, since that’s what unlocks the 50% pricing discount described in Step 1.
Step 8: Handle errors and rate limits gracefully
Google has not published fixed RPM or TPM caps specifically for Nano Banana 2 in its public docs — limits are tied to your project’s billing tier and quota configuration rather than a flat per-model number. That means your error handling needs to be defensive rather than tuned to a documented ceiling:
import time
from google import genai
from google.genai import errors
client = genai.Client(api_key="your-api-key-here")
def generate_with_retry(prompt, max_retries=3, backoff_base=2):
for attempt in range(max_retries):
try:
response = client.models.generate_content(
model="gemini-3.1-flash-image",
contents=prompt,
)
return response
except errors.ClientError as e:
if "RESOURCE_EXHAUSTED" in str(e) or "429" in str(e):
wait = backoff_base ** attempt
print(f"Rate limited, retrying in {wait}s...")
time.sleep(wait)
else:
raise
raise RuntimeError("Max retries exceeded")Exponential backoff with a small number of retries handles transient rate limiting without hammering the API when you hit a genuine quota wall. If retries consistently fail, the fix is almost always requesting a quota increase through the Google Cloud console rather than tuning your backoff further.
Step 9: Compare Nano Banana 2 against the rest of the field
Nano Banana 2 doesn’t exist in a vacuum. Depending on your use case, Seedream 5.0, Midjourney V8.2, and Nano Banana Pro are all reasonable alternatives, and each optimizes for something different. This table summarizes what’s publicly documented as of September 2026:
| Model | API model ID | 1K image price | Best for | Access |
|---|---|---|---|---|
| Nano Banana 2 | gemini-3.1-flash-image | $0.067 (std) / $0.034 (batch) | Production throughput, general use | Gemini API, GA |
| Nano Banana 2 Lite | Not officially published | ~$0.034 (std) / ~$0.0168 (batch) | High-volume, cost-sensitive workloads | Gemini API |
| Nano Banana Pro | gemini-3-pro-image | Not fully published | Dense text rendering, multi-image consistency | Gemini API, GA |
| Seedream 5.0 Pro | seedream5_pro | Varies by host platform | Reference-image fusion, interactive editing | REST API via fal, Runway Dev |
| Midjourney V8.2 | Not a public API model | Subscription-based, no per-image API price | Stylized, artistic output | Web/Discord, no official developer API |
Seedream 5.0 Pro and Lite became available on developer platforms including Runway Dev and fal in July and September 2026 respectively, with Text-to-Image and Edit as its two main endpoints, according to a September 7, 2026 press release covered by the National Law Review. Its differentiator is multi-image fusion and interactive editing rather than raw generation speed, which makes it a stronger fit for workflows built around iterative refinement of an existing image rather than one-shot generation.
Midjourney, meanwhile, updated its default model from V7 to V8.1 in June 2026, and a subsequent update pushed V8.2 to default status in late July 2026, according to Midjourney’s own release notes. Midjourney still does not expose an official public developer API in the way Google and ByteDance’s platforms do, so it remains a poor fit for programmatic, code-driven pipelines like the ones in this tutorial, even though its output quality on stylized and artistic prompts is well regarded.
Step 10: Build a simple multi-prompt image generation CLI
Putting the previous steps together, here’s a small but complete command-line tool that reads prompts from a text file, generates images at a specified resolution, logs cost, and reports a summary at the end. This is the closest thing in this tutorial to a “complete working project”:
#!/usr/bin/env python3
"""nano_banana_cli.py — batch-generate images from a prompt file."""
import argparse
import json
import os
import time
from datetime import datetime
from google import genai
RESOLUTION_COSTS = {
"512x512": 0.045,
"1024x1024": 0.067,
"2048x2048": 0.101,
"4096x4096": 0.151,
}
def main():
parser = argparse.ArgumentParser(description="Batch-generate images with Nano Banana 2")
parser.add_argument("prompt_file", help="Text file, one prompt per line")
parser.add_argument("--resolution", default="1024x1024", choices=RESOLUTION_COSTS.keys())
parser.add_argument("--output-dir", default="./generated")
parser.add_argument("--delay", type=float, default=1.0)
args = parser.parse_args()
os.makedirs(args.output_dir, exist_ok=True)
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
with open(args.prompt_file) as f:
prompts = [line.strip() for line in f if line.strip()]
total_cost = 0.0
success_count = 0
for i, prompt in enumerate(prompts):
try:
response = client.models.generate_content(
model="gemini-3.1-flash-image",
contents=f"{prompt} :: output resolution {args.resolution}",
)
for part in response.candidates[0].content.parts:
if part.inline_data is not None:
filename = os.path.join(args.output_dir, f"img_{i:03d}.png")
with open(filename, "wb") as out:
out.write(part.inline_data.data)
total_cost += RESOLUTION_COSTS[args.resolution]
success_count += 1
print(f"[{i+1}/{len(prompts)}] Saved {filename}")
except Exception as e:
print(f"[{i+1}/{len(prompts)}] FAILED: {e}")
time.sleep(args.delay)
print(f"nDone: {success_count}/{len(prompts)} succeeded")
print(f"Estimated total cost: ${total_cost:.3f}")
if __name__ == "__main__":
main()Run it with python3 nano_banana_cli.py prompts.txt --resolution 1024x1024, where prompts.txt contains one image description per line. This gives you a reusable tool for anything from generating placeholder assets for a game prototype to producing a batch of marketing image variants for A/B testing.
Step 11: Test output quality against your actual use case
Before committing to Nano Banana 2 for a production feature, run a small quality test across a representative sample of your real prompts — not generic demo prompts. Save outputs at each resolution tier and evaluate them against your specific requirements: does text render legibly if your images include labels or captions? Does the model handle your brand’s specific product categories well? Does it maintain consistency across a series of related prompts?
A repeatable way to do this without manual guesswork is to generate the same prompt at 1K, 2K, and 4K and compare file sizes, generation latency, and visual fidelity side by side:
import time
import os
from google import genai
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
def quality_test(prompt, resolutions=("512x512", "1024x1024", "2048x2048", "4096x4096")):
results = []
for res in resolutions:
start = time.time()
response = client.models.generate_content(
model="gemini-3.1-flash-image",
contents=f"{prompt} :: output resolution {res}",
)
elapsed = time.time() - start
for part in response.candidates[0].content.parts:
if part.inline_data is not None:
filename = f"quality_test_{res}.png"
with open(filename, "wb") as f:
f.write(part.inline_data.data)
size_kb = len(part.inline_data.data) / 1024
results.append({"resolution": res, "latency_s": round(elapsed, 2), "size_kb": round(size_kb, 1)})
return results
for r in quality_test("A detailed architectural blueprint of a modern house, labeled dimensions"):
print(r)This kind of side-by-side test is especially important for text-heavy prompts, since text rendering quality tends to vary more between resolution tiers than photographic subjects do.
Step 12: Set up monitoring for production use
Once Nano Banana 2 is powering a live feature, you need basic observability: how many requests are succeeding, what your actual daily spend looks like, and whether latency is drifting. A minimal approach that doesn’t require a full observability stack is to extend the JSONL logging from Step 6 with a daily summary script:
import json
from collections import defaultdict
from datetime import datetime
def daily_summary(log_file="nano_banana_usage.jsonl"):
daily_totals = defaultdict(lambda: {"count": 0, "cost": 0.0})
with open(log_file) as f:
for line in f:
entry = json.loads(line)
day = entry["timestamp"][:10]
daily_totals[day]["count"] += 1
daily_totals[day]["cost"] += entry["cost_usd"]
for day, stats in sorted(daily_totals.items()):
print(f"{day}: {stats['count']} images, ${stats['cost']:.2f}")
daily_summary()For anything beyond a small side project, pipe this data into a proper dashboard (Grafana, a simple internal admin panel, or your existing analytics stack) rather than reading log files by hand every day.
Step 13: Wrap Nano Banana 2 in a small FastAPI service
A CLI tool is fine for one-off batches, but most real applications need image generation behind a proper HTTP endpoint that a frontend, mobile app, or another backend service can call. This section builds a minimal but complete FastAPI wrapper around everything covered so far: resolution selection, cost tracking, and retry logic in one deployable service.
pip install fastapi uvicorn# app.py
import os
import time
import base64
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from google import genai
from google.genai import errors
app = FastAPI(title="Nano Banana 2 Image Service")
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
RESOLUTION_COSTS = {
"512x512": 0.045,
"1024x1024": 0.067,
"2048x2048": 0.101,
"4096x4096": 0.151,
}
class ImageRequest(BaseModel):
prompt: str
resolution: str = "1024x1024"
class ImageResponse(BaseModel):
image_base64: str
resolution: str
estimated_cost_usd: float
@app.post("/generate", response_model=ImageResponse)
def generate(req: ImageRequest):
if req.resolution not in RESOLUTION_COSTS:
raise HTTPException(400, f"Unsupported resolution: {req.resolution}")
for attempt in range(3):
try:
response = client.models.generate_content(
model="gemini-3.1-flash-image",
contents=f"{req.prompt} :: output resolution {req.resolution}",
)
for part in response.candidates[0].content.parts:
if part.inline_data is not None:
encoded = base64.b64encode(part.inline_data.data).decode("utf-8")
return ImageResponse(
image_base64=encoded,
resolution=req.resolution,
estimated_cost_usd=RESOLUTION_COSTS[req.resolution],
)
raise HTTPException(502, "Model returned no image data")
except errors.ClientError as e:
if "429" in str(e) and attempt < 2:
time.sleep(2 ** attempt)
continue
raise HTTPException(502, f"Gemini API error: {e}")
@app.get("/health")
def health():
return {"status": "ok", "model": "gemini-3.1-flash-image"}Start the service locally with uvicorn app:app --reload --port 8000, then test it with a simple POST request:
curl -X POST http://localhost:8000/generate
-H "Content-Type: application/json"
-d '{"prompt": "A cozy mountain cabin at dusk, snow falling", "resolution": "1024x1024"}'This gives you the complete working project this tutorial promised: a deployable API that any frontend can call, with resolution validation, cost estimation, and basic retry handling already wired in. From here, the realistic next steps for a production deployment are adding authentication (an API key or JWT layer in front of your own endpoint), containerizing it with Docker, and deploying it to a platform like Cloud Run, Fly.io, or AWS Lambda depending on your existing infrastructure. None of those steps are specific to Nano Banana 2 — they’re the same steps you’d take for any FastAPI service — which is exactly the point: once the model integration itself is solid, the rest is standard backend engineering.
Common pitfalls when integrating Nano Banana 2
Most Nano Banana 2 integration problems trace back to a handful of recurring mistakes. Here are the ones worth checking first:
- Hardcoding the wrong model ID. Nano Banana 2 is
gemini-3.1-flash-image, notgemini-2.5-flash-image(the original Nano Banana) orgemini-3-pro-image(Nano Banana Pro). Mixing these up is the single most common source of confusion in early integrations. - Assuming a flat per-image price. Cost scales with resolution. A script that generates everything at 4K by default can burn through budget more than twice as fast as one defaulting to 1K, without anyone noticing until the bill arrives.
- Not using the Batch API for non-interactive workloads. Leaving a nightly catalog-generation job on standard pricing instead of batch pricing means paying roughly double for no benefit, since nothing about that workload actually needs real-time responses.
- Treating Nano Banana 2 Lite pricing as officially confirmed across all resolutions. Google has only clearly documented Lite’s 1K price point; extrapolating 2K or 4K Lite costs from unofficial sources risks budget surprises.
- Skipping retry logic entirely. Because Google does not publish fixed rate limits for this model, transient 429 errors are expected at higher volume. Scripts without backoff logic fail unpredictably under load.
- Storing the API key in source control. This sounds obvious, but committing a
.envfile or hardcoding a key directly in a script remains one of the most common security mistakes in API tutorials that get copy-pasted into real projects. - Not validating aspect ratio support before launch. Since Google hasn’t published a complete aspect-ratio table for Nano Banana 2, teams sometimes discover a needed ratio isn’t well supported only after building a feature around it.
Example output and expected results
Running the CLI tool from Step 10 against a five-prompt file at 1K resolution should produce output resembling this in your terminal:
[1/5] Saved ./generated/img_000.png
[2/5] Saved ./generated/img_001.png
[3/5] Saved ./generated/img_002.png
[4/5] Saved ./generated/img_003.png
[5/5] Saved ./generated/img_004.png
Done: 5/5 succeeded
Estimated total cost: $0.335If a prompt fails, expect an error line like [3/5] FAILED: 429 RESOURCE_EXHAUSTED rather than a silent skip, assuming you’re using the retry-and-log pattern from Steps 6 and 8. A completely silent failure with no error message and no output file usually points to a malformed request body rather than a quota issue — check that your resolution string matches one of the four documented tiers exactly.
Troubleshooting common Nano Banana 2 API issues
These are the issues developers run into most often, in roughly the order you’re likely to hit them:
- “Model not found” errors: Double-check the exact model ID string,
gemini-3.1-flash-image. A typo likegemini-3-1-flash-image(hyphens instead of periods) will fail silently in some SDK versions and loudly in others. - Empty inline_data in the response: This usually means the model returned a text-only response instead of an image, often because the prompt was flagged by safety filters. Check
part.textfor a rejection message before assuming the API call itself failed. - 429 RESOURCE_EXHAUSTED errors under moderate load: Since rate limits aren’t published per model, this is often a project-level quota issue. Request a quota increase through the Google Cloud console rather than assuming your code is broken.
- Unexpectedly high costs at month-end: Audit your resolution defaults. A single function defaulting to 4K instead of 1K across thousands of calls compounds fast, and it’s the most common cause of billing surprises with this API.
- Inconsistent aspect ratios across requests: Since the full aspect ratio list isn’t officially published, test your specific ratio needs directly against the live API rather than assuming documentation from a related Gemini model applies.
- Batch API jobs stuck in a pending state: Batch processing is asynchronous by design, and it is not unusual for jobs to take significantly longer than a standard synchronous call. Build your pipeline to poll for completion rather than expecting an immediate response.
- SDK import errors after installation: If
from google import genaifails, confirm you installedgoogle-genaiand not the older, deprecatedgoogle-generativeaipackage — the two coexist in PyPI and have different import paths. - Authentication errors despite a valid-looking key: Confirm billing is actually enabled on the associated Google Cloud project. A syntactically valid API key tied to a project without billing enabled will still return authentication failures for paid-tier models like Nano Banana 2.
Advanced tips for production workloads
Once the basics are working, a few refinements make a meaningful difference at scale. First, cache generated images aggressively by prompt hash if your application ever re-requests the same or similar prompts — regenerating an identical image costs the same as generating a new one, and a simple hash-based cache eliminates that waste entirely. Second, consider routing low-priority or exploratory generations to Nano Banana 2 Lite and reserving standard Nano Banana 2 for anything customer-facing, since the roughly 2x cost difference compounds quickly at volume. Third, if your application needs both generation and iterative editing of the same image, evaluate Seedream 5.0 Pro’s Edit endpoint alongside Nano Banana 2, since Google’s model is optimized for fresh generation rather than reference-image-driven editing.
Finally, build resolution selection into your application logic rather than hardcoding a single tier everywhere. A thumbnail generation path has no business paying 4K prices, while a hero banner for a landing page probably should. Segmenting resolution by use case, rather than by convenience, is where most of the realistic cost savings in a Nano Banana 2 integration actually come from.
When to choose a different AI image generator entirely
Nano Banana 2 is a strong default for programmatic, API-driven image generation, but it is not the right tool for every job. If your priority is dense, accurate text rendering in complex layouts or multi-panel infographics, Nano Banana Pro’s higher cost is usually justified. If your workflow revolves around iterative editing of existing images with reference-image fusion, Seedream 5.0 Pro’s dedicated Edit endpoint is purpose-built for that in a way Nano Banana 2 currently is not. If you need a stylized, artistic aesthetic and don’t need programmatic API access at all, Midjourney V8.2 remains a strong choice for manual, creative-first workflows, even without an official developer API. The right model is almost always a function of the specific job, not a single universal “best” pick, which is exactly why building a small internal router — as outlined in Steps 9 and the advanced tips above — pays off once you’re running more than one type of image workload.
Frequently asked questions
What is the official API model ID for Nano Banana 2?
The model ID is gemini-3.1-flash-image, accessible through the Gemini API with an API key from Google AI Studio.
How much does Nano Banana 2 cost per image?
Standard pricing is $0.045 for 0.5K, $0.067 for 1K, $0.101 for 2K, and $0.151 for 4K resolution, according to Google’s Gemini Developer API pricing page. Batch API pricing cuts each of these roughly in half.
Is Nano Banana 2 different from Nano Banana Pro?
Yes. Nano Banana 2 (Gemini 3.1 Flash Image) is the faster, cheaper production tier. Nano Banana Pro (Gemini 3 Pro Image) is the higher-cost, higher-quality tier built for complex text rendering and multi-image consistency, though Google has not published a full per-image price table for Pro.
What is Nano Banana 2 Lite and how does it differ from standard Nano Banana 2?
Nano Banana 2 Lite is a cheaper variant priced at roughly $0.034 per 1K image on standard pricing, compared to $0.067 for standard Nano Banana 2. Google has not published an official model ID or a full resolution table for Lite, so treat its documentation as less complete than the standard tier.
Does Nano Banana 2 support batch processing for lower costs?
Yes, Google’s Batch API applies roughly a 50% discount across all four resolution tiers, making it the most effective cost lever for non-interactive, asynchronous workloads like overnight catalog generation.
What are the rate limits for the Nano Banana 2 API?
Google has not published fixed RPM or TPM limits specific to this model. Limits are tied to your project’s billing tier and quota configuration, so production applications should implement retry logic with exponential backoff rather than relying on a documented ceiling.
Can I use Nano Banana 2 for commercial projects?
Yes, Nano Banana 2 is a generally available, billed API product intended for production and commercial use, unlike preview-only or research-restricted models. Review Google’s current Gemini API terms of service for any usage restrictions specific to your industry or use case.
How does Nano Banana 2 compare to Midjourney for API-driven workflows?
Midjourney does not offer an official public developer API as of September 2026, which makes it a poor fit for the kind of programmatic, code-driven pipeline covered in this tutorial. Nano Banana 2 is purpose-built for API integration, while Midjourney remains oriented toward manual, web and Discord-based creative workflows.