Nano Banana Pro API Docs: Endpoints, Parameters & Limits

Search “nano banana pro api docs” and the top organic result is a 13,000-word tutorial with 135 code blocks and 46 example images — and no consolidated parameter table, no error code, no rate limit, and no install line before the first from google import genai. A product page sitting in the top five advertises “endpoint references, parameter details, code samples” in its snippet and contains zero endpoints and zero code samples. Even the AI Overview hedges on the one string every integration actually needs: model string google/nano-banana-pro — or equivalent provider strings depending on your API gateway.

That hedge is the whole problem. This page is the reference those pages are not: the endpoints, the model IDs and how they map, every request parameter with its allowed values and its effect on price, the raw JSON that comes back on both routes, the limits and retention windows, the error codes and which ones to retry, and a dated per-image cost table. Read it top to bottom or jump to the table you need.

Everything here was read from the providers’ own pages on September 10, 2026 and is stamped as such; Google’s own pricing page carried a “Last updated 2026-09-08 UTC” footer when we pulled it. Modellix operates this blog and is one of the two routes described below, so treat its column as a disclosed commercial interest, not a neutral verdict. One scoping note against our own archive: the Nano Banana Pro API overview already walks the call shape end to end, including a submit-and-poll loop, webhooks and error handling. What it does not carry — and what this page adds — is the reference layer: a consolidated parameter table per route, the per-model limits and reference-image ceilings, the raw request and response envelopes, the error-code table with a retry policy, and the funding-tier rate limits. Read that one for the narrative, this one when you are writing or debugging the integration.

Quick reference: the Nano Banana Pro endpoints and model IDs

“Nano Banana Pro” is a marketing name. Google’s model ID for it is gemini-3-pro-image; the same model is listed as google/nano-banana-pro in a gateway catalog. Those two strings are the difference between a request that works and a 404, so map them once and stop guessing.

Marketing name	Google model ID	Gateway model string	Family role
Nano Banana Pro	gemini-3-pro-image	google/nano-banana-pro	Highest-fidelity creative tier, 4K, thinking on by default
Nano Banana Pro Edit	gemini-3-pro-image	google/nano-banana-pro-edit	Instruction-based editing on the gateway edit route, 1–14 reference images
Nano Banana 2	gemini-3.1-flash-image	google/nano-banana-2	Speed-first generalist
Nano Banana 2 Lite	gemini-3.1-flash-lite-image	google/nano-banana-2-lite	Cheapest tier
Nano Banana (legacy)	gemini-2.5-flash-image	google/nano-banana	Original release; Google recommends migrating off it

The model IDs above are the ones Google’s Nano Banana image-generation documentation uses as of September 10, 2026. Note what that page says about the legacy row and what it does not: it still documents gemini-2.5-flash-image as a selectable model and recommends transitioning to Nano Banana 2 Lite. It does not announce a shutdown date, and neither will this page. If the cheaper tier turns out to be the right call for your workload, our Nano Banana 2 API guide covers its endpoint surface and its own resolution ladder.

Two endpoints reach Pro. Pick one; you do not need both.

Route	Method and path	Auth header	Returns
Google direct	POST https://generativelanguage.googleapis.com/v1beta/interactions	x-goog-api-key	The finished image in the same response
One-key gateway	POST https://api.modellix.ai/api/v1/google/nano-banana-pro	Authorization: Bearer	A task_id you poll, or a webhook
One-key gateway (task lookup)	GET https://api.modellix.ai/api/v1/tasks/{task_id}	Authorization: Bearer	Status, result resources, actual billed amount
One-key gateway (edit)	POST https://api.modellix.ai/api/v1/google/nano-banana-pro-edit	Authorization: Bearer	Same task contract as generation

Here is an unhelpful habit worth breaking early: copy the path from the model’s own API page, not from a different model’s example. Modellix publishes a per-model OpenAPI spec — the one for Nano Banana Pro declares /api/v1/google/nano-banana-pro, while quickstart examples elsewhere on the same docs site use a /{provider}/{model}/async form for other providers’ models. Pattern-matching the suffix across models is how you end up debugging a route that was never there.

Request parameters for Nano Banana Pro, field by field

Google’s page explains its parameters in prose and repeats them across Python, JavaScript, Java and REST tabs. Here they are in one place for the generation call.

Parameter	Type	Required	Accepted values	Default	Effect on cost
model	string	Yes	gemini-3-pro-image	—	Selects the Pro price tier
input	array or string	Yes	Text part, image part, or both	—	Each input image bills ~$0.0011
response_format	object	No	{"type":"image"}	Text-or-image	Requesting an image is what triggers image billing
response_format.aspect_ratio	string	No	Ratio set below	Provider default	None
response_format.image_size	string	No	1K, 2K, 4K	1K	4K roughly doubles the per-image price
tools	array	No	[{"type":"google_search"}]	Off	Grounding is billed separately, per search request
generation_config	object	No	Thinking-level controls	Thinking on for Pro	Thinking tokens bill as output text

The gateway exposes the same capability as four flat fields, which is the whole point of its request shape:

Parameter	Type	Required	Accepted values	Default
prompt	string	Yes	Any text, minimum length 1	—
aspectRatio	string	No	1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9	1:1
imageSize	string	No	1K, 2K, 4K	not stated in the model’s schema (Google’s route defaults to 1K)
image	string[]	Yes on the edit route, absent on generation	1–14 image URLs	—

Two field-level facts that decide most first-request failures. Pro has no 512px tier — the smallest output is 1K, so a request copied from a Nano Banana 2 example that sets a half-resolution size will not have a Pro equivalent. And image is an array, not a string: the edit route takes one to fourteen URLs and treats all of them as reference context for a single instruction, so an editor UI that sends image: "https://..." fails validation rather than quietly working.

A first request, end to end, on both routes

Start with the SDK, because the official page does not tell you to install it. Google’s libraries page is where the install lines live: pip install google-genai for Python, npm install @google/genai for JavaScript and TypeScript. Then set the key you created in Google AI Studio as an environment variable so it never lands in your source tree.

export GEMINI_API_KEY="your-key-here"

curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image",
    "input": [{"type": "text", "text": "A labelled cutaway diagram of a two-stage gearbox, studio lighting"}],
    "response_format": {"type": "image", "aspect_ratio": "4:3", "image_size": "2K"}
  }'

The same call in Python, where the image arrives as base64 you have to decode and write yourself:

import base64, os
from google import genai

client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

interaction = client.interactions.create(
    model="gemini-3-pro-image",
    input="A labelled cutaway diagram of a two-stage gearbox, studio lighting",
    response_format={"type": "image", "aspect_ratio": "4:3", "image_size": "2K"},
)

with open("gearbox.png", "wb") as f:
    f.write(base64.b64decode(interaction.output_image.data))

The gateway route is a different shape because it is asynchronous: the submit call returns no image at all, just a handle. Set MODELLIX_API_KEY from the key you create once in the Modellix console, then submit and poll.

curl --request POST \
  --url https://api.modellix.ai/api/v1/google/nano-banana-pro \
  --header "Authorization: Bearer $MODELLIX_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "prompt": "A labelled cutaway diagram of a two-stage gearbox, studio lighting",
    "aspectRatio": "4:3",
    "imageSize": "2K"
  }'

curl --request GET \
  --url https://api.modellix.ai/api/v1/tasks/task-def456 \
  --header "Authorization: Bearer $MODELLIX_API_KEY"

The submit call answers with a task handle rather than an image:

{
  "code": 0,
  "message": "success",
  "data": {
    "status": "pending",
    "task_id": "task-def456",
    "model_id": "google/nano-banana-pro",
    "get_result": {
      "method": "GET",
      "url": "https://api.modellix.ai/api/v1/tasks/task-def456"
    }
  }
}

Do not spin on that second call in a tight loop. Back off — one second, then two, then four — or skip polling entirely by sending an X-Webhook-URL header on the submit call, in which case the gateway POSTs the result to your HTTPS endpoint when the task reaches a terminal state and expects any 2xx back. The full lifecycle of both routes, including the states your job passes through and where each one leaves you, is laid out below.

How the two routes differ in shape, not in model: Google’s Interactions API answers a request with the finished image, while the gateway answers with a task handle that settles into success or failed and can be delivered by webhook instead of polling. Diagram generated for this article; not a console screenshot.

Nano Banana Pro endpoint reference

See the parameters, request schema and task routes for google/nano-banana-pro and its edit variant.

View Docs

The response envelope: what actually comes back

This is the artifact no page in the top five prints, and it is the one you need if you are integrating over plain HTTP rather than through a vendor SDK. On Google’s route the image lives inside steps, not at the top level: the SDK convenience properties output_image and output_text are shortcuts over an array that can interleave text and image blocks when the model narrates its work.

{
  "steps": [
    {
      "type": "model_output",
      "content": [
        { "type": "text", "text": "Here is the diagram you asked for." },
        { "type": "image", "mime_type": "image/png", "data": "<base64>" }
      ]
    }
  ]
}

Iterate steps and check each block’s type if you want both the caption and the file; reach for output_image only when you know the response contains exactly one image. On the gateway route the submit response is the task handle shown in the previous section, and the task lookup returns the payload below once the job finishes. Note billing and result_expires_at — the first tells you what was actually charged, the second tells you when to stop expecting the asset to exist.

{
  "code": 0,
  "message": "success",
  "data": {
    "status": "success",
    "task_id": "task-def456",
    "model_id": "google/nano-banana-pro",
    "duration": 3500,
    "billing": { "status": "succeeded", "amount": 0.1206 },
    "result": {
      "resources": [
        { "url": "https://cdn.example.com/images/abc123.png", "type": "image",
          "width": 2048, "height": 1536, "format": "png", "role": "primary" }
      ],
      "metadata": { "image_count": 1 },
      "extensions": { "submit_time": 1757491200000, "end_time": 1757491203500 }
    },
    "result_expires_at": 1758096000000
  }
}

The task status field takes pending or processing while a job is in flight and settles on one of three terminal values: success, failed, or canceled. duration is milliseconds and only appears on a finished task; error only appears on a failed one. A webhook delivery carries a body identical to this response — including billing — plus X-Modellix-Event, X-Modellix-Task-ID, X-Modellix-Delivery-ID and X-Modellix-Retry-Count headers, which is why deduplicating on X-Modellix-Delivery-ID is the one idempotency measure worth building on day one — and why a webhook handler must treat canceled as a completed delivery, not as a failure to retry. All of this is documented in the Modellix REST API guide and the task-result schema; it is also the part of the contract that appears on none of the pages competing for this query. The other Nano Banana models share the identical envelope, so once this shape is parsed you have parsed the family — our family-wide Nano Banana API docs guide covers the parts that are common across all four.

Limits: resolutions, reference images, retention, and rate limits

Pro’s ceilings are real and they are not the family’s ceilings — the family page quotes the widest numbers across four models, which is how an integration ends up sized for a limit the model it calls does not have.

Limit	Nano Banana Pro	Where it is documented
Output resolutions	1K, 2K, 4K — no 512px tier	Pro parameter table; Google notes 512px is added by Nano Banana 2 only
Default output size	1K unless you set image_size / imageSize	Google: “Gemini 3 image models generate 1K images by default”
Pixel ceiling per tier	1K = 1024×1024; 2K = up to 2048×2048; 4K = up to 4096×4096	Google pricing footnotes for image output
Aspect ratios	10 values, 1:1 through 21:9 (no ultra-wide bands)	Pro parameter table
Reference images, Google direct	Up to 6 objects, 5 characters and 3 style references — the same 14, split by category	Google’s per-model reference-image table
Reference images, gateway edit route	1–14 URLs per request, all treated as context	Pro Edit parameter table
Generated-result retention	About 7 days	REST API guide
Uploaded input files	16 MB per file, 10 files per team, 2 concurrent uploads	File API limits
Team rate limit	100 RPM at the lowest funding tier, up to 1,000 RPM at a $1,000 top-up	Team entitlements table
Concurrent generation tasks	2 at the lowest tier, up to 100 at a $1,000 top-up	Team entitlements table
Request-log window	30 days maximum per query	Logs endpoint

That reference-image row is the one worth re-reading, because it is where a Pro integration most often gets sized wrong. Google’s page does say “up to 14 reference images”, but that is the family-wide headline; the table underneath it separates the ceilings, and Pro’s are the tightest of the three Gemini 3 image models — six objects, five characters and three style references, which add up to the same 14 the family headline quotes. If you are porting a multi-reference pipeline from Nano Banana 2, those are the numbers that move. On the gateway’s edit route the documented input is a flat 1–14 array, so check which route your pipeline actually calls before you pick a limit.

Rate limits and concurrency are not a single global number either. They scale with your team’s single top-up amount, published as a funding-tier entitlements table with no email required until you need something beyond it:

Single top-up	Concurrent tasks	Rate limit (RPM)
Under $10	2	100
$10	10	100
$100	20	200
$200	30	300
$500	50	500
$1,000	100	1,000
Custom	Custom	Custom

Two more of those rows deserve a sentence each. Retention is not a suggestion. Results live about seven days on the gateway, and Google’s route hands you base64 in a response body you have to persist yourself — either way, download to your own storage at generation time rather than at render time. And the RPM figure is a per-team ceiling with headers attached: a 429 carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, so the correct reaction is to read the reset timestamp rather than to sleep for a fixed interval and hope. Steady-state throughput, meanwhile, is usually governed by the concurrent-task column rather than by RPM — a 4K Pro job that runs for several seconds will hit two concurrent tasks long before it hits 100 requests in a minute.

Aspect ratio and output size are the two knobs that move your bill, so they are worth fixing before you write the integration rather than after. Ratios and tiers as documented for Pro on September 10, 2026. Diagram generated for this article.

Error codes and what to retry

Every failure on the gateway route arrives in the same envelope, and the message is formatted as "<Category>: <detail>" — which means you can branch on the category string instead of pattern-matching prose.

{ "code": 400, "message": "Invalid parameters: parameter 'prompt' is required" }

Status	Meaning	Typical cause on this model	Retry?
400	Bad Request	Missing prompt, an imageSize outside 1K/2K/4K, image sent as a string instead of an array	No — fix the request
401	Unauthorized	Missing, malformed, or revoked key	No
402	Payment Required	Balance exhausted	No — top up
404	Not Found	Wrong task ID, or a model string that is not in the catalog	No
413	Payload Too Large	Uploaded input file above 16 MB	No
429	Too Many Requests	Rate or concurrency ceiling hit; read X-RateLimit-Reset	Yes — back off
500	Internal Server Error	Upstream processing error	Yes — retry up to three times
503	Service Unavailable	Service temporarily unavailable, or an open circuit breaker	Yes — back off and retry

Every row above is the gateway’s own published error table, read on September 10, 2026 — including the 503 row — at the Modellix REST API guide. The rule that keeps a retry loop honest: 4xx other than 429 is your bug and retrying it just burns quota, while 429 and 5xx are transient and want exponential backoff. Google’s direct route has its own error surface with its own codes and its own quota page, so a retry policy written for one route will not transfer unchanged to the other — a detail worth deciding before you build the abstraction over both.

What a Nano Banana Pro image costs, read September 10, 2026

Google bills Pro on tokens and publishes the per-image equivalent in a footnote; the gateway bills per image with the tiered rate printed on the model page. Both sets of numbers below were read from the live pages today, and both move without notice.

Route	1K	2K	4K	Basis
Google direct, Standard	$0.134	$0.134	$0.24	$120 / 1M image output tokens
Google direct, Batch	$0.067	$0.067	$0.12	50% reduction, up to 24h turnaround
Gateway, google/nano-banana-pro	$0.1206	$0.1206	$0.2160	Displayed per-image list price
Gateway, google/nano-banana-pro-edit	$0.1215	$0.1215	$0.2169	Displayed per-image list price

The Google column is the per-image equivalent Google itself prints on its Gemini API pricing page: image output is priced at $120 per million tokens, a 1K or 2K image consumes 1,120 tokens, and a 4K image consumes 2,000. Input images bill separately at roughly $0.0011 each, and there is no free tier for Pro on the paid API. The gateway column is what the Nano Banana Pro model page displays, in $/img — the unit its pricing documentation defines for every image model on the platform.

Do the arithmetic for your own workload rather than someone else’s headline: a 1,000-image run at 2K is $134 on Google’s standard tier, $67 in batch, or $120.60 on the gateway; doubling the resolution instead of the volume roughly doubles the Google figure to $240. A note of honesty about the route choice, since a gateway blog recommending a gateway deserves one: for a workload that never leaves Google’s models and can absorb a 24-hour batch window, Google’s batch tier is simply cheaper — a gateway buys one key and one bill across vendors, not a lower unit price at every tier. Note the qualifier: strip the batch window out and the same table above shows the gateway undercutting Google’s standard 4K rate, so the two routes trade places depending on how you buy. What the key buys is breadth: the same credential and the same submit-poll contract reach the rest of the catalog, which our unified AI API explainer describes. The per-image depths, including why the widely copied “$0.15 an image” figure is wrong, are in our Nano Banana Pro pricing breakdown.

Start Calling Nano Banana Pro

Log in to Modellix to call google/nano-banana-pro and the rest of the image and video catalog through the same one API key.

Login

Where the official documentation stops

The gaps are not cosmetic. Each one costs an integrator a search, a support thread, or an hour of guessing, and every one of them was absent from all five top-ranking pages we read on September 10, 2026.

• Parameters are documented in prose and in code, never in a table. Google’s page spreads aspect_ratio, image_size and grounding across four language tabs and roughly 150 sub-headings. If you need “what values does this field accept”, you are reading code samples to find out. The consolidated tables are above.
• There is no first-party error-code reference on the model page. Failures on the Google route surface through generic Gemini API errors, and the gateway’s code table lives on a different page than its model pages. Both tables exist; neither is where you look first.
• Rate limits live on a different page than the model. The tier table exists, but it is not on the model page and it is not on the parameters page either — so “how many Pro jobs can I run at once” takes three clicks to answer. The X-RateLimit-* headers on a 429 tell you your effective ceiling without any clicking at all.
• No raw response body. The official page teaches SDK property access — interaction.output_image — which is fine until you are writing a service in a language without an official SDK, or debugging a truncated payload you cannot see.
• No install line. The documentation begins at from google import genai. The install command is real and documented, just on a different page, which is a strange omission in a quickstart.

Two smaller ones are worth knowing about before you file a ticket. Data residency is not stated on the model or parameters page for either route, so if your compliance posture depends on where generation runs, ask the specific provider before you build. And the family’s headline capability numbers are not the per-model ones — “up to 14 reference images” is the Gemini 3 headline, and Pro’s own slice of that 14 is split into narrower categories: six objects, five characters and three style references. The tier the flat “up to 14 images of objects” belongs to is Nano Banana 2 Lite, which is how a project gets sized against a limit the model it calls does not have.

Use this section as a checklist rather than a complaint. If a docs page answers four of the five gaps above, bookmark it. On September 10, 2026, the top five answered none.

Frequently Asked Questions

Is there an official Nano Banana Pro API?

Yes. Nano Banana Pro is Google’s gemini-3-pro-image model, reachable on the Gemini API through the Interactions API endpoint. The same model is also served through unified API gateways under a provider/model string such as google/nano-banana-pro. There is no separate “Nano Banana Pro API” product — the name is a nickname for the model.

What is the Nano Banana Pro API endpoint?

Two routes qualify. Google direct: POST https://generativelanguage.googleapis.com/v1beta/interactions with an x-goog-api-key header. Gateway: POST https://api.modellix.ai/api/v1/google/nano-banana-pro with Authorization: Bearer, followed by GET https://api.modellix.ai/api/v1/tasks/{task_id}. Copy the path from the specific model’s own API page rather than from another model’s example.

Is the Nano Banana Pro API free?

No. Google’s pricing page lists no Free Tier for gemini-3-pro-image — the free column reads “not available” for both input and output at every tier. Gateway access is prepaid pay-as-you-go, billed per generated image. Google AI Studio’s web interface is free to use, but that is a browser playground, not API access.

How do I get a Nano Banana Pro API key?

There are two legitimate sources: a Gemini API key from Google AI Studio, or a key from a provider console that fronts the same model. The choice determines which auth header you send and whether you are billed per token or per image — our Nano Banana Pro API key guide walks through both, including rotation and the 401/403 failures each one produces.

What resolutions and aspect ratios does Nano Banana Pro support?

1K, 2K and 4K output, with no 512px tier — that half-resolution option belongs to Nano Banana 2, not Pro. Ten aspect ratios are accepted: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9 and 21:9. The ultra-wide bands some faster models accept are not in Pro’s enum.

How much does one Nano Banana Pro image cost?

As of September 10, 2026: $0.134 per image at 1K or 2K and $0.24 at 4K on Google’s standard tier, or about half that in batch mode, plus roughly $0.0011 per input image. The same model’s displayed per-image rate on Modellix is $0.1206 at 1K/2K and $0.2160 at 4K. Both lists change without notice — re-read them before you budget.

Does the Nano Banana Pro API support webhooks or async tasks?

Google’s Interactions API returns the generated image in the response to a single request, so there is nothing to poll. The gateway route is asynchronous by design: submit returns a task_id, you either poll the task endpoint or send an X-Webhook-URL header and receive a callback that mirrors the task-result payload, including the amount actually billed.

What is the difference between gemini-3-pro-image and google/nano-banana-pro?

They are two strings for the same model. gemini-3-pro-image is Google’s own model identifier, used in the model field of a direct Gemini API call. google/nano-banana-pro is a gateway catalog slug in provider/model form, used in the request path. Mixing them — sending the slug to Google, or the raw ID to a gateway — is the most common cause of a 404 on a first integration.

How do the Nano Banana models differ across the family?

Pro is the fidelity tier at gemini-3-pro-image, and the only one of the three Gemini 3 image models with tighter reference-image ceilings than the family headline: six objects, five characters and three style references, against the ten and fourteen the Flash tiers allow. Nano Banana 2 is the speed-first generalist at gemini-3.1-flash-image; Nano Banana 2 Lite is the cheapest at gemini-3.1-flash-lite-image, and the only one capped at 1K output; and gemini-2.5-flash-image is the original release, still documented with a recommendation to migrate off it rather than a shutdown notice.

---

Provider details, model IDs and pricing reflect public information as of September 10, 2026 and change frequently — re-read the live pages before you commit budget or ship an integration. Both routes described here were documented from their own first-party pages on that date; the Google material is vendor-neutral and the Modellix figures are a same-day snapshot of a displayed list price, not a standing claim. This article was written by Modellix, which operates this blog and has a commercial interest in the single-key route it describes. Access image and video models, including the leading Chinese models, through a single API key at modellix.ai.

Cover image: illustrative Modellix artwork; it is not a Google or Modellix product screenshot, and the two in-body figures are diagrams generated for this article.