If you want to call the Nano Banana 2 API from your own code, the first thing to know is that “Nano Banana 2” is Google’s name for gemini-3.1-flash-image — its fast generalist image model — and you can reach it two ways. You call Google’s official Gemini API directly through the Interactions API (billed per token), or you call a unified API like Modellix that fronts the same model behind one key (billed per image). This guide gives you working code for both paths, the full parameter reference, the often-skipped nano-banana-2-edit variant for image editing and video frames, the async contract, and error handling. For the gentle zero-to-first-image walkthrough, see the how to use Nano Banana guide — this page assumes you are past that and want the integration spec.
One disclosure up front: we run Modellix, an aggregator that offers Nano Banana 2 alongside 210+ other image and video models through a single REST API. We have a commercial interest when Modellix appears in the comparison. Every model ID, parameter, and price below was pulled from Google’s and Modellix’s own documentation on July 29, 2026. Where we could not verify something, we say so.
What the Nano Banana 2 API is — and the model ID behind it
“Nano Banana” is a nickname, not a separate product. Google’s image-generation docs state it plainly: “Nano Banana is the name for Gemini’s native image generation capabilities.” When you call the Nano Banana 2 API, you are calling the Gemini model gemini-3.1-flash-image under the hood.
The full family maps to distinct model IDs:
| Nano Banana name | Model ID | Role |
|---|---|---|
| Nano Banana (original) | gemini-2.5-flash-image (legacy) |
Superseded by 2 |
| Nano Banana 2 | gemini-3.1-flash-image |
Fast generalist — this page |
| Nano Banana 2 Lite | gemini-3.1-flash-lite-image |
Cheapest, high-volume drafts |
| Nano Banana Pro | gemini-3-pro-image |
Highest fidelity, complex compositions |
Model IDs from Google’s image-generation docs, retrieved July 29, 2026.
One naming trap worth knowing: Nano Banana 2 runs on Gemini 3.1, while Nano Banana Pro runs on Gemini 3 — the higher version number is the faster generalist, not the premium tier. Pro is the high-fidelity model despite the lower number. If your integration needs Pro’s legible in-image text or brand-accurate layouts, that model has its own reference — see the Nano Banana Pro API guide. This page stays on the “2.”
Two ways to call the Nano Banana 2 API
There are two legitimate access paths, and picking the right one matters more than any single line of code.
Path A — Google’s official Gemini API. You call Google directly through the Interactions API, setting model: "gemini-3.1-flash-image" with a response_format that specifies type: "image", an aspect_ratio, and an image_size (512px, 1K, 2K, or 4K), per Google’s docs. Billing is per token at $60 per 1M output tokens. You get one provider, but it is the source of truth.
Path B — a unified API (Modellix). You call one REST endpoint with one API key and swap the model name in the path. The same asynchronous task contract works for every model — Nano Banana 2 today, a video model tomorrow. Billing is per image, and every call posts to a submit endpoint, returns a task_id, and gets polled or delivered via webhook. Modellix is a distribution layer, not the model maker.
| Official Gemini API | Unified API (Modellix) | |
|---|---|---|
| You integrate | One provider (Google) | One key, many image/video models |
| Model reference | gemini-3.1-flash-image |
google/nano-banana-2 in the URL path |
| Billing | Per token ($60/1M output) | Per image |
| Call pattern | Synchronous (Interactions API) | Asynchronous (submit → poll → retrieve) |
| Webhooks | Not standard for images | X-Webhook-URL header supported |
| Best when | You only need Google’s models | You want to compare or mix providers |
Both routes hit the same underlying Google model — the images come from identical inference. Which path is “better” depends on whether your architecture needs one provider or many, not on either producing different output or being cheaper.
Path A: Google’s official Gemini API
On Google’s path, you call the Interactions API with the model gemini-3.1-flash-image and a response_format block. Here is the minimal curl call:
1 | curl -s -X POST \ |
And the same call in Python using Google’s genai SDK:
1 | from google import genai |
The response is synchronous — you get the image data back in the same call. Google also supports multi-turn editing by passing a previous_interaction_id, so you can refine an image across several requests without re-sending the full history.
Two things to know about the official path. First, Google bills per token, not per image — the per-image prices on their pricing page are just the token math done for you. A 1K square image consumes 1,120 output tokens at $60/1M = $0.067. Second, there is no free tier for image generation on Google’s API; the free Gemini API key covers text only.
Path B: Unified API (Modellix)
On the unified path, every model uses the same asynchronous contract. You POST a prompt to a submit endpoint, get a task_id back, then poll until the result is ready — or catch it on a webhook.
Submit the job:
1 | curl --request POST \ |
The submit returns a task, not an image:
1 | { |
Poll for the result — call GET /api/v1/tasks/{task_id} with the same Authorization header until status is success, then read the image URL from data.result.resources[].url:
1 | curl --request GET \ |
Or skip polling with a webhook. Send an X-Webhook-URL header on submit and Modellix POSTs to your URL when the task finishes. Each callback carries X-Modellix-Event (prediction.task.succeeded / .failed / .canceled) plus X-Modellix-Task-ID and X-Modellix-Delivery-ID headers. Generated results live for 7 days on Modellix — download and persist the asset before then.
This is not saying Modellix is the cheapest path — Google’s Batch mode halves the official API prices for work that can run asynchronously — but the contract is uniform across every model on the platform, which matters when your integration spans multiple providers.
Parameters reference
On the unified API, only prompt is required:
| Parameter | Type | Required | Values |
|---|---|---|---|
prompt |
string | Yes | Your image description |
aspectRatio |
string | No | 1:1, 1:4, 1:8, 2:3, 3:2, 3:4, 4:1, 4:3, 4:5, 5:4, 8:1, 9:16, 16:9, 21:9 |
imageSize |
string | No | 512, 1K, 2K, 4K |
On Google’s official path the same controls live inside response_format — aspect_ratio and image_size with the same value sets (Google uses "512px", "1K", "2K", "4K" for image_size and 14 aspect ratios). The knobs are the same; the names differ slightly.
Resolution is a budget decision, not just a quality one. Going from 1K to 4K more than doubles the cost on either path — $0.067 → $0.151 on Google direct, $0.0575 → $0.1248 on Modellix — so ask for the smallest resolution your use case actually needs.
The edit endpoint: nano-banana-2-edit
This is the part most Nano Banana 2 content skips. Alongside plain text-to-image, there is a dedicated edit endpoint on the same asynchronous contract:
1 | POST https://api.modellix.ai/api/v1/google/nano-banana-2-edit/async |
Per the Modellix edit model page, Nano Banana 2 Edit “rapidly modifies existing images — or extracts and edits frames from a video — based on natural-language text prompts.” It is an image-to-image model, so its parameters differ from the generate endpoint:
| Parameter | Type | Required | Notes |
|---|---|---|---|
prompt |
string | Yes | The editing instruction |
image |
string[] | No* | Up to 14 image URLs; up to 10 when video is also provided |
video |
string | No* | Public HTTPS URL, max 15 MB — a frame is extracted and edited |
videoMimeType |
string | No | video/mp4, mpeg, mpg, mpegps, mov, avi, wmv, flv |
aspectRatio |
string | No | Same 14 options as generate |
imageSize |
string | No | 512, 1K, 2K, 4K |
*At least one of image or video must be provided.
A minimal edit call — restyle an existing image — looks like this:
1 | curl --request POST \ |
On Google’s official path, the same capability is exposed as text-and-image-to-image editing through the Interactions API — you pass both a text prompt and image inputs in the same call, with multi-turn refinement via previous_interaction_id. The edit endpoint is billed slightly above plain generation at each resolution.
The async request/response contract
Every Modellix model uses the same submit-poll-retrieve lifecycle, so wiring this once covers every model on the platform. The full step-by-step loop with backoff and file saving is in the how to use Nano Banana guide; this section is the contract reference.
Submit returns a task. A successful POST responds with status: "pending" and a task_id. The get_result object tells you exactly where to poll.
Poll until terminal. Call GET /api/v1/tasks/{task_id} with the same Authorization header. The status progresses through pending → processing → success (or failed / canceled). On success, the image URL lives at data.result.resources[].url.
Or use webhooks. Include X-Webhook-URL in the submit headers. Modellix POSTs to that URL on terminal state with X-Modellix-Event classifying the outcome. Each callback includes billing.amount in the body so you can track cost per task.
Result TTL is 7 days. Download the asset when you get it — the URL is not permanent.
Pricing at a glance
Price has its own dedicated breakdown, so here is the summary. On the unified path, Nano Banana 2 costs per image:
| Resolution | Modellix (per image) | Google direct (per image, standard) |
|---|---|---|
| 512 | $0.0403 | $0.045 |
| 1K | $0.0575 | $0.067 |
| 2K | $0.0851 | $0.101 |
| 4K | $0.1248 | $0.151 |
Modellix prices from the nano-banana-2 model page; Google prices from Gemini API pricing. Both retrieved July 29, 2026.
Google’s Batch API halves every Google-row figure for work that can wait. The edit variant costs slightly more at each tier ($0.0419 → $0.0598 → $0.0869 → $0.1265 on Modellix). For the full ladder — the token math, Lite model pricing, and where “2” sits against the rest of the family — see the Nano Banana 2 price breakdown.
To be clear about the boundary: Nano Banana 2 is Google’s model. A unified API distributes it; it does not build it.
Error codes and retry strategy
Every error on Modellix is a unified JSON whose code matches the HTTP status. The only distinction worth building into your retry logic is which ones are transient:
| Status | Meaning | Retry? |
|---|---|---|
| 400 | Invalid parameters | No — fix the request |
| 401 | Invalid, missing, or expired API key | No — provide a valid key |
| 402 | Insufficient balance | No — top up first |
| 404 | Unknown task/model/provider ID | No — check the ID |
| 429 | Rate or concurrency limit hit | Yes — exponential backoff; check X-RateLimit-Reset |
| 500 | Internal server error | Yes — retry with backoff |
| 503 | Service temporarily unavailable | Yes — retry with backoff |
Error codes from the Modellix REST API reference, July 29, 2026.
The rule of thumb: 4xx (except 429) are your bug — fix the request. 429 and 5xx are transient — back off exponentially and retry. For the full key lifecycle behind the 401/402 cases — creating, storing, rotating, and validating keys — start from the Google provider page on Modellix.
FAQ
What is the Nano Banana 2 API model ID? It is gemini-3.1-flash-image — Google’s ID for the model marketed as “Nano Banana 2 (Gemini 3.1 Flash Image),” described as the fast generalist workhorse for image generation, per Google’s image-generation docs.
How do I get a Nano Banana 2 API key? You have two options. For Google’s official path, create an API key at Google AI Studio. For the Modellix unified path, create a key at modellix.ai/console/api-key. The Nano Banana API key guide walks through both processes end to end.
Is the Nano Banana 2 API free? Not for image generation. Google’s pricing page lists the free tier as “Not available” for every image model. Unified APIs are pay-as-you-go; any starter credit is a platform-specific claim to verify at signup.
How do I edit an image with the Nano Banana 2 API? Use the nano-banana-2-edit endpoint with a prompt plus an image array (up to 14 URLs) or a video URL (public HTTPS, max 15 MB) to extract and edit a frame. On Google’s path, it is text-and-image-to-image editing through the Interactions API with multi-turn refinement via previous_interaction_id.
Why does the API return a task ID instead of an image? Image generation runs asynchronously on the unified path. The submit call returns a task_id with a pending status; you poll GET /api/v1/tasks/{task_id} until success and read the image URL, or catch it on a webhook. Google’s Interactions API is synchronous and returns the image data directly.
How is Nano Banana 2 different from Nano Banana Pro? Nano Banana 2 (gemini-3.1-flash-image) is the speed-first generalist at $60/1M output tokens; Nano Banana Pro (gemini-3-pro-image) is the high-fidelity tier at $120/1M, built for legible in-image text and brand-accurate 4K layouts. The version numbering misleads — 3.1 is the faster generalist, 3 Pro is the premium tier. See the Nano Banana Pro API guide.
What aspect ratios and resolutions are supported? Fourteen aspect ratios from 1:1 and 16:9 to extreme formats like 8:1 and 21:9, and four output sizes: 512, 1K, 2K, 4K. Only prompt is required on the unified API; both dials are optional. Google’s path uses response_format.aspect_ratio and response_format.image_size with the same value sets.
Do I need Google Cloud to use the Nano Banana 2 API? No. You need an API key — either an official Gemini API key from Google AI Studio, or a key from a unified API like Modellix that fronts the same model.
Model IDs, endpoints, parameters, and pricing were retrieved from first-party pages on July 29, 2026: Google’s Gemini image-generation and pricing docs, the Modellix REST API reference, and the Modellix model pages for nano-banana-2 and nano-banana-2-edit. Nano Banana 2 is a Google model; IDs and rates can change without notice — verify against the linked pages before you build. Modellix is one distribution layer that fronts Google’s endpoints and does not build the model. Access image and video models, including the leading Chinese models, through a single API key at modellix.ai.
