Nano Banana API docs cover: dark amber technical artwork with the MODELLIX wordmark, a two-line API docs title, and a spec capsule

Searching for “nano banana api docs” in 2026 returns two kinds of pages: Google’s own Gemini documentation, which is accurate but sprawling and billed in tokens, and aggregator explainers, several of which are frozen in 2025 — still calling Nano Banana “Gemini 2.5 Flash Image” and quoting $0.03 per image. Neither gives you a dated, working integration guide. This article is that guide: the current model family map, both access paths, pricing pulled from live pages today, and code you can run.

Here is the one-line version: Nano Banana is Google’s name for its Gemini image models. The family is gemini-3-pro-image (Pro), gemini-3.1-flash-image (Nano Banana 2), and gemini-3.1-flash-lite-image (Lite), with gemini-2.5-flash-image retired as the legacy generation. You call them either directly through Google’s synchronous Interactions API, or through a unified API like Modellix, which wraps them in an asynchronous submit-poll-retrieve task. All prices below were pulled from the live Google pricing page and Modellix model pages on August 28, 2026. Full disclosure up front: Modellix is an aggregator and benefits if you pick its path; the numbers are presented as displayed, and the comparison is deliberately narrow.

What the official Nano Banana API documentation actually covers

Google’s official Nano Banana image-generation documentation is the reference for the direct path. It documents one call shape — the Interactions API — for both generation and multi-turn editing, plus aspect ratio and image size options, grounding with Google Search, and a note that every generated image carries a SynthID watermark. The same page lists the model IDs and their intended roles, and it is kept current: as of August 2026 it is the only ranking page that names all four generations correctly.

What the official docs do not do is compare access paths. Google bills image output in tokens, and the per-image equivalent only appears in the pricing page footnotes. That is where the ranking pages diverge: piapi.ai’s “Nano Banana API documentation” (September 2025) and similar aggregator posts still describe the 2025 model generation, and thin sales pages skip error handling, result retention, and the async lifecycle that a unified API introduces. Those are the gaps this article closes.

The Nano Banana model family: which model ID to call

The naming confusion on the SERP has a simple cure: there are four model IDs, and each maps to a clear role. Google’s docs page describes Nano Banana 2 as the “generalist workhorse” and Nano Banana Pro as the “premium choice for the most complex visual tasks.”

Model ID Marketing name Google’s guidance Modellix route
gemini-2.5-flash-image Nano Banana (legacy) Superseded by Nano Banana 2; migrate off for new integrations google/nano-banana
gemini-3.1-flash-image Nano Banana 2 Generalist workhorse: 4K generation, world knowledge, reliable text rendering, multiple reference images google/nano-banana-2
gemini-3.1-flash-lite-image Nano Banana 2 Lite Efficiency specialist: ultra-low latency, cost-effective generation and editing google/nano-banana-2-lite
gemini-3-pro-image Nano Banana Pro Premium: highest world knowledge, localization, brand consistency, precision control google/nano-banana-pro

Three practical notes. First, the legacy ID still appears in 2025 tutorials; treat those pages as historical. Second, the family also ships edit variants (gemini-3.1-flash-image handles multi-turn editing through previous_interaction_id, and dedicated edit routes exist on aggregators). Third, every output is SynthID-watermarked regardless of path — that is a Google platform property, not a per-vendor choice. For a walkthrough of getting a key for the workhorse model, see our Nano Banana 2 API key guide.

Two ways to reach the Nano Banana API: Google direct vs a unified API

You have two legitimate access paths, and they differ in three structural ways: authentication, call shape, and billing unit.

Dimension Google direct (Gemini API) Unified API (Modellix)
Auth x-goog-api-key header per request Authorization: Bearer <key> per request
Call shape Synchronous: request → image bytes in the response Async: submit → task_id → poll → output URL
Billing unit Tokens (image output priced per 1M tokens) Per image, tiered by output size
Key scope Google models only 210+ image and video models behind one key
Result delivery Inline in the response URL, retained for 7 days

The practical difference is the sync/async split. Google’s Interactions API returns the image in the HTTP response — simple for one-off calls, but it blocks for the full generation time. A unified API returns a task_id immediately and delivers the finished image on a later poll or webhook, which suits batch pipelines. The async lifecycle is the single biggest integration surprise when moving from Google’s official path to an aggregator, and it is explained in the diagram below.

Diagram contrasting Google's synchronous Nano Banana Interactions call with a unified API's async submit, poll, and retrieve task lifecycle

Async vs sync Nano Banana calls, illustrated. Google direct returns image bytes in the response; a unified API returns a task_id, then delivers a URL on poll or webhook. Diagram generated August 28, 2026.

Modellix is an aggregator, and this comparison is not neutral: we sell access to these models. The reason a developer picks a unified path is rarely unit price — it is operational, like keeping several vendors behind one key and one invoice. For the background on that model, see what a unified AI API means.

Nano Banana API endpoints and parameters

Both paths expose the same model family through different contracts. On Google’s official path, the endpoint is POST https://generativelanguage.googleapis.com/v1beta/interactions with the x-goog-api-key header. On a unified API, the endpoint pattern is POST https://api.modellix.ai/api/v1/{provider}/{model}/async — for example google/nano-banana-pro — followed by GET https://api.modellix.ai/api/v1/tasks/{task_id}.

The parameters that matter, as documented on both sides (Google docs and Modellix model pages, August 2026):

Parameter Google direct Modellix unified Notes
prompt Required (text or image parts in input[]) Required (prompt in JSON body) The image description
aspectRatio Via response_format; 14 options on Nano Banana 2 incl. 4:1, 1:4, 8:1, 1:8 Same enum on the model page Pro shows 10 options (no ultra-wide)
imageSize response_format.image_size: 0.5K / 1K / 2K / 4K imageSize: 512, 1K, 2K, 4K Higher tiers cost more per image
previous_interaction_id Multi-turn editing on the direct path Edit routes (*-edit) instead Editing is a first-class capability
Thinking On by default for Nano Banana 2; interim thought images not billed Not exposed as a parameter Direct-path concept

Two contract differences worth flagging before you write code. Google’s official path takes the model ID plus a parts array (input), while unified APIs take a flat prompt string per model. And the direct path returns output_image inline, while the unified path returns result.resources[].url after polling. The code section below handles both shapes.

Nano Banana API pricing: what a generation actually costs

Pricing is the section where most ranking pages are stale, so everything below carries an access date. Figures were pulled from the Google Gemini API pricing page and the Modellix Nano Banana Pro and Nano Banana 2 model pages on August 28, 2026. Google prices image output per token; the per-image equivalents below are computed from Google’s own published token counts. Modellix prices per image, tiered by output size, exactly as displayed.

Google direct — equivalent per image (from $ per 1M image tokens):

Model 0.5K (512px) 1K 2K 4K
gemini-2.5-flash-image (legacy) — $0.039 — —
gemini-3.1-flash-image (Nano Banana 2) $0.045 $0.067 $0.101 $0.151
gemini-3.1-flash-lite-image (Lite) — $0.0336 — —
gemini-3-pro-image (Pro) — $0.134 $0.134 $0.24

Source: Gemini Developer API pricing, accessed August 28, 2026. Pro image input is billed separately at $0.0011 per image (560 tokens).

Modellix — displayed price per image:

Route 512 1K 2K 4K
google/nano-banana (legacy) — $0.0351 — —
google/nano-banana-2 $0.0450 $0.0603 $0.0909 $0.1359
google/nano-banana-2-lite — $0.0306 — —
google/nano-banana-pro — $0.1206 $0.1206 $0.2160

Source: Modellix model pages, accessed August 28, 2026. Prices as displayed at access time; they change without notice.

Two honest observations. First, on the same tier on the day pulled, Modellix’s displayed figures sit a few cents below Google’s token equivalents (e.g. Nano Banana 2 at 1K: $0.0603 vs $0.067; Pro at 4K: $0.2160 vs $0.24). This is a snapshot of two live price lists, not a standing claim — both sides move, and a comparison means nothing once either page updates. Second, aggregator pricing is per image with no token accounting to reason about, which is convenient for budgeting but not the same as Google’s per-token granularity. If you want the free-credit path covered separately, our Nano Banana API free access guide walks through it.

Integration code: curl and Python for both paths

The code below uses the exact endpoints and parameters documented above. Google direct is a single synchronous call; the unified path is submit-then-poll.

Google direct — curl (synchronous Interactions API):

1
2
3
4
5
6
7
8
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.1-flash-image",
    "input": [{"type": "text", "text": "A studio portrait of a banana in a spacesuit"}],
    "response_format": {"type": "image", "mime_type": "image/png", "aspect_ratio": "4:3", "image_size": "1K"}
  }'

The response contains output_image.data (base64) plus output_text. Google’s Python SDK wraps the same call as client.interactions.create(model="gemini-3.1-flash-image", input="...", response_format={...}).

Modellix — curl submit and poll (async):

1
2
3
4
5
6
7
8
9
10
11
12
13
# 1) Submit the task
curl -s -X POST "https://api.modellix.ai/api/v1/google/nano-banana-pro/async" \
  -H "Authorization: Bearer $MODELLIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A studio portrait of a banana in a spacesuit", "aspectRatio": "4:3", "imageSize": "1K"}'
# → {"code":0,"data":{"status":"pending","task_id":"task-abc123",
#    "get_result":{"method":"GET","url":"https://api.modellix.ai/api/v1/tasks/task-abc123"}}}

# 2) Poll the task until status is success or failed
curl -s "https://api.modellix.ai/api/v1/tasks/task-abc123" \
  -H "Authorization: Bearer $MODELLIX_API_KEY"
# → {"code":0,"data":{"status":"success","task_id":"task-abc123",
#    "result":{"resources":[{"url":"https://cdn.example.com/images/abc123.png", ...}]}}}

Modellix — Python poll loop with backoff (no extra SDK, requests only):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
import time
import requests

API_KEY = "YOUR_MODELLIX_API_KEY"
BASE = "https://api.modellix.ai/api/v1"
headers = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

submit = requests.post(
    f"{BASE}/google/nano-banana-pro/async",
    headers=headers,
    json={"prompt": "A studio portrait of a banana in a spacesuit",
          "aspectRatio": "4:3", "imageSize": "1K"},
).json()
task_id = submit["data"]["task_id"]

for attempt in range(30):
    time.sleep(min(2 ** attempt, 20))          # 2s, 4s, 8s ... capped at 20s
    res = requests.get(f"{BASE}/tasks/{task_id}", headers=headers).json()
    status = res["data"]["status"]
    if status == "success":
        print(res["data"]["result"]["resources"][0]["url"])   # download within 7 days
        break
    if status == "failed":
        raise RuntimeError(res["data"]["error"])

If you prefer push over polling, send the X-Webhook-URL header with the submit request; Modellix POSTs the task result to it on completion (headers X-Modellix-Event, X-Modellix-Task-ID, X-Modellix-Retry-Count; your receiver must answer 2xx). The full async and webhook contract lives in the Modellix REST API documentation. For the Pro endpoint specifically, including how to get a key for it, see our Nano Banana Pro API key guide.

Nano Banana API Reference

See the async submit-poll lifecycle, webhook contract, and parameter tables for every Nano Banana route.

View Docs

Error handling, rate limits, and the gotchas the docs don’t headline

Ranking pages skip error handling almost entirely, so this section is the part you will not find elsewhere. The error semantics below are the ones you actually hit on the unified path (Modellix docs, August 2026); Google’s direct path uses the same HTTP families but its own error bodies.

Status Meaning What to do
400 Malformed request (missing prompt, bad aspectRatio/imageSize enum) Fix the payload; X-Mdlx-User-Id with invalid values also returns 400
401 Missing or invalid API key Check the header (x-goog-api-key vs Authorization: Bearer)
402 Insufficient balance Top up before retrying; no retry will succeed
404 Unknown model route or task Confirm the model slug (google/nano-banana-pro, not a guess)
429 Rate limited Back off with exponential retry; webhook deliveries get retried on 429
5xx Provider or platform error Retry; transient by nature

Three gotchas in particular. Results expire in 7 days: unified API output is a URL, and the docs state results are saved for 7 days — download promptly. The async call is not instant: a “pending” task can take tens of seconds for 4K output, so a synchronous integration pattern will time out. Webhook retries have rules: Modellix retries on 429 and on 5xx-style failures, but a 4xx response from your receiver (other than 429) stops delivery — your endpoint must return 2xx even for validation errors.

How to pick your path: a short decision checklist

There is no universal right answer, but the decision collapses to four questions:

  • How many vendors do you integrate? One Google key for one model family → direct is fine. Several vendors or frequent model swaps → a unified key removes per-vendor onboarding.
  • How do you want to budget? Per-token billing gives Google’s granularity; per-image pricing gives a fixed cost per output tier. Neither is objectively better — pick the unit you can forecast.
  • Sync or async? One-off generation in a script → direct. Batch pipelines, queues, or callbacks → the async task model.
  • Do you need models Google does not host? Chinese image and video models (Kling, Seedream, Wan, and others) are not on the Gemini API; a unified API exposes them without needing a China-region account.

A reasonable default for a new integration: start on Google direct with gemini-3.1-flash-image to validate quality, and move to a unified API when you add a second vendor or need per-image cost accounting at volume. And to repeat the honest caveat: this is not a claim that Modellix is the cheapest route for every workload — the dated tables above are the evidence, and they will be stale within weeks.

Start Generating with Nano Banana

Log in to run Nano Banana Pro, Nano Banana 2, and 200+ other models on one Modellix key.

Login

FAQ

What is the current Nano Banana API model ID?

As of August 2026 the current IDs are gemini-3.1-flash-image (Nano Banana 2), gemini-3.1-flash-lite-image (Nano Banana 2 Lite), and gemini-3-pro-image (Nano Banana Pro). The 2025 ID gemini-2.5-flash-image is the legacy generation and should not be used for new integrations.

Is the Nano Banana API free?

Google’s paid tier bills image output per token (Nano Banana 2 at $60 per 1M image tokens as of August 28, 2026); free-tier availability is limited and requires a paid API key for production. Aggregators bill per image and may offer new-user credits — check the current terms on the provider you choose.

Why is a unified API asynchronous when Google’s official API is synchronous?

Google’s Interactions API returns image bytes in the HTTP response. Unified APIs submit a task and return a task_id, then you poll GET /api/v1/tasks/{task_id} or receive a webhook. The async model exists to run many generations in parallel without holding connections open.

Does Modellix bill per image?

Yes. Modellix model pages display per-image prices tiered by output size — for example google/nano-banana-2 at $0.0450 (512px) up to $0.1359 (4K) as displayed on August 28, 2026. Google direct bills in tokens instead; the two units are not directly interchangeable.

How long are Nano Banana API results kept?

On Modellix’s unified path, generated results are saved for 7 days; the output URL must be downloaded before expiry. Google’s direct path returns the image inline in the response, so retention does not apply the same way.

Can I edit images with the Nano Banana API?

Yes. On Google’s official path, pass previous_interaction_id with a new prompt to refine a generated image. Aggregators expose dedicated edit routes (for example google/nano-banana-pro-edit). The docs recommend the Pro edit variant for complex creative edits and Nano Banana 2 Edit for fast, high-volume changes.

Pricing and availability reflect public information as of August 28, 2026, and change frequently. Validate against the live Google pricing page and your provider’s model pages before committing. Access image and video models, including the leading Chinese models, through a single API key at modellix.ai.