NewMiniMax H3 Lite is live: our cheapest video model, at a launch price until Dec 31. Try it free

OG filename: how-to-use-nano-banana-api-cover-v3.png
All guides
How-to

How to Use the Nano Banana API in 2026

Generate and edit Nano Banana, Nano Banana 2 and Nano Banana Pro images up to 4K from your own code with the AiWings API: create a key, send one request, and get a permanent image link. Step by step, in cURL, JavaScript and Python.

·6 min read·

How to Use the Nano Banana API in 2026

Want Nano Banana images in your own app, script or automation? This guide shows how to make them with the AiWings API, step by step. One AiWings key covers all three versions, Nano Banana, Nano Banana 2 and Nano Banana Pro, from quick 1K drafts to 4K finals with exact text, plus edits from reference images. You pay per image from your AiWings credits and get back a permanent link to every file.

What you need

  • An AiWings account. Sign in with Google; new accounts get 10 free credits, enough for 2 Nano Banana images.
  • An AiWings API key, which you create in the next step.
  • Somewhere to run code on a server: a script, a backend route, a serverless function or an automation tool that can send HTTP requests. Keys don’t work from browser or mobile app code, where anyone could read them.

Step 1: Create an API key

  1. 1Sign in to AiWings and open the API page in your dashboard.
  2. 2Click Create key, give it a name (for example “my-app production”) and, if you like, a monthly credit limit.
  3. 3Copy the key. It starts with aiw_live_ and is shown only once.
  4. 4Save it as an environment variable on the machine or service that will call the API.
export AIWINGS_API_KEY="aiw_live_your_key_here"

The API uses the same credits as AiWings in ChatGPT, Claude and the dashboard, so there’s no separate plan to buy. Every request sends the key in the Authorization header as a Bearer token.

Create an API key

Step 2: Choose a Nano Banana model

Pick the version with the model field and the size with quality:

Modelmodel valuequalityReference imagesCost per imageBest for
Nano Banananano-banana1KUp to 35 credits ($0.05)Fast, low-cost images and quick edits
Nano Banana 2nano-banana-21K, 2K, 4KUp to 148–19 credits ($0.08–$0.19)The best quality for the price, up to 4K
Nano Banana Pronano-banana-pro1K, 2K, 4KUp to 1419–38 credits ($0.19–$0.38)Studio-grade detail and the most exact text

Prices are at the top-up rate of $0.01 per credit, and plans include more credits per dollar. Each finished job reports exactly what it cost in its credits field, and GET /v1/models lists every price. Nano Banana Pro costs the same at 1K and 2K, so ask for 2K. For edits, aspect_ratio "match_input_image" keeps the shape of your reference.

Step 3: Make your first image

Send a POST request to /v1/images with a prompt, the model and a quality. With "wait": true you get the finished image back in the same call. This one is a product ad made with Nano Banana 2 at 2K, for 13 credits ($0.13):

1curl https://aiwings.io/api/v1/images \
2 -H "Authorization: Bearer $AIWINGS_API_KEY" \
3 -H "Content-Type: application/json" \
4 -d '{
5 "prompt": "A luxury perfume bottle in a splash of golden liquid on black marble, dramatic studio lighting, premium product ad",
6 "model": "nano-banana-2",
7 "quality": "2K",
8 "aspect_ratio": "4:5",
9 "wait": true
10 }'
11
12# Still "processing"? Ask again with the id:
13curl "https://aiwings.io/api/v1/images/IMAGE_ID?wait=30" \
14 -H "Authorization: Bearer $AIWINGS_API_KEY"
POST /v1/imagesShell

With "wait": true the request holds until the image is ready, for up to 60 seconds, so most images come back in one call with status "succeeded". Higher quality settings can take longer; if the status is still "processing", the loop asks again with GET /v1/images/{id}?wait=30.

output.url is a permanent link to the file. If an image fails, status is "failed", error.message says why, and the credits are refunded automatically. Every image you make through the API also shows up in your AiWings library.

Step 4: Get exact text with Nano Banana Pro

When the words in the image have to be right, such as a poster, a label or a menu, use Nano Banana Pro and put the exact text in the prompt. At 2K it costs 19 credits ($0.19):

1curl https://aiwings.io/api/v1/images \
2 -H "Authorization: Bearer $AIWINGS_API_KEY" \
3 -H "Content-Type: application/json" \
4 -d '{
5 "prompt": "A screen-printed gig poster with the words NIGHT MARKET in bold letters across the top, paper lanterns and food stalls below, warm orange and teal",
6 "model": "nano-banana-pro",
7 "quality": "2K",
8 "aspect_ratio": "4:5",
9 "wait": true
10 }'
11
12# Still "processing"? Ask again with the id:
13curl "https://aiwings.io/api/v1/images/IMAGE_ID?wait=30" \
14 -H "Authorization: Bearer $AIWINGS_API_KEY"
POST /v1/imagesShell

With "wait": true the request holds until the image is ready, for up to 60 seconds, so most images come back in one call with status "succeeded". Higher quality settings can take longer; if the status is still "processing", the loop asks again with GET /v1/images/{id}?wait=30.

output.url is a permanent link to the file. If an image fails, status is "failed", error.message says why, and the credits are refunded automatically. Every image you make through the API also shows up in your AiWings library.

Step 5: Keep your product, change the scene

Pass public image URLs in reference_images and describe the new scene; Nano Banana keeps the product and its label. Nano Banana takes up to 3 references, Nano Banana 2 and Pro up to 14. Already made the image with AiWings? Pass its id as source_generation_id instead.

1curl https://aiwings.io/api/v1/images \
2 -H "Authorization: Bearer $AIWINGS_API_KEY" \
3 -H "Content-Type: application/json" \
4 -d '{
5 "prompt": "Put these tea tins on a busy morning market stall, soft daylight, keep the labels exactly as they are",
6 "model": "nano-banana",
7 "aspect_ratio": "3:2",
8 "reference_images": [
9 "https://example.com/tea-tins.png"
10 ],
11 "wait": true
12 }'
13
14# Still "processing"? Ask again with the id:
15curl "https://aiwings.io/api/v1/images/IMAGE_ID?wait=30" \
16 -H "Authorization: Bearer $AIWINGS_API_KEY"
POST /v1/imagesShell

To upload a file from your computer first, use POST /v1/uploads, then pass the url it returns in reference_images. The API docs show the full flow.

See what Nano Banana makes

Real, unedited results from the three Nano Banana versions, each made from a single request.

A faceted crystal perfume bottle labeled AURELIA suspended in a splash of liquid gold with floating rose petals on a dark background
Premium product adsNano Banana 2 · 4K
A 1960s screen-printed travel poster for the fictional desert city Al-Waha, with a giant half sun over dunes and a camel caravan
Exact text on a printed posterNano Banana Pro · 2K
A white-washed Andalusian-inspired city on a floating island above the clouds at golden hour with waterfalls of mist
Epic scale with fine detailNano Banana Pro · 4K
The same three TIDE, EMBER and MOSS tea tins from the reference image on a rustic wooden market stall with kraft paper tags and dried herbs
Keep the product, change the sceneNano Banana · 1K

More models with the same key

Your key isn’t limited to Nano Banana. The same key, balance and request format cover every video and image model on AiWings. To switch, change the model field: video models go to POST /v1/videos and image models to POST /v1/images.

Modelmodel valueEndpointFrom
Seedance 2.0seedance-2.0/v1/videos50 credits ($0.50) for 5 seconds at 480p
Seedance 2.5seedance-2.5/v1/videos65 credits ($0.65) for 5 seconds at 480p
MiniMax H3minimax-h3/v1/videos50 credits ($0.50) for 5 seconds at 768p
MiniMax H3 Highspeedminimax-h3-highspeed/v1/videos20 credits ($0.20) for 5 seconds at 768p
MiniMax H3 Liteminimax-h3-lite/v1/videos10 credits ($0.10) for 5 seconds at 480p
GPT Image 2.6 Flaregpt-image-2.6-flare/v1/images7 credits ($0.07) per image
GPT Image 2.6 Sunburstgpt-image-2.6-sunburst/v1/images7 credits ($0.07) per image
GPT Image 2.5 Flaregpt-image-2.5-flare/v1/images2 credits ($0.02) per image
GPT Image 2.5 Sunburstgpt-image-2.5-sunburst/v1/images2 credits ($0.02) per image
GPT Image 2gpt-image-2/v1/images2 credits ($0.02) per image
GPT Image 1.5gpt-image-1.5/v1/images2 credits ($0.02) per image
Nano Banananano-banana/v1/images5 credits ($0.05) per image
Nano Banana 2nano-banana-2/v1/images8 credits ($0.08) per image
Nano Banana Pronano-banana-pro/v1/images19 credits ($0.19) per image
Seedream 5 Liteseedream-5-lite/v1/images5 credits ($0.05) per image
Grok Imaginegrok-imagine/v1/images3 credits ($0.03) per image
Flux Fastflux-fast/v1/images1 credit ($0.01) per image

GET /v1/models returns the same list with every price, size and option, so your code can check what’s available instead of hard-coding it.

See every model with samples

Things to know

  • quality sets the size: 1K, 2K or 4K on Nano Banana 2 and Pro, and 1K on Nano Banana.
  • Put any words you want in the image in the prompt exactly as they should appear. Nano Banana Pro is the most reliable for long or small text.
  • For edits, aspect_ratio "match_input_image" keeps the shape of your reference image.
  • Send an Idempotency-Key header with each new job (the JavaScript and Python examples do). If a request times out and you retry with the same key, you get the same job back instead of paying twice.
  • Each key has its own rate limit, and you can give each key a monthly credit cap so a bug in one app can’t spend your whole balance.
  • Output URLs are public but unguessable, like a share link. Download the file to your own storage if you need to control who can see it.

If something goes wrong

  • 401 authentication_failed: the key is missing, mistyped or revoked. Check the Authorization header reads Bearer followed by your key.
  • 400 invalid_request: a field isn’t allowed for that model, for example a quality or aspect ratio it doesn’t support. The error’s param names the field to fix.
  • 402 insufficient_credits: your balance can’t cover the image. Top up in the dashboard and send the request again.
  • 403 spend_limit_reached: this key hit its monthly credit limit. Raise or remove the limit on the API page.
  • 429 rate_limited or too_many_jobs: you’re sending too fast or have too many jobs rendering at once. Wait for the Retry-After time, or for a image to finish.
  • The image failed with a content error: the prompt or image was blocked by the model’s safety filter. Reword it; the credits were already refunded.

Bottom line

You don’t need a Google Cloud or Gemini API account to put Nano Banana in your product. One AiWings key gives your code all three Nano Banana versions up to 4K, plus GPT Image, Seedream, Flux and video models, billed from one balance, with permanent links and automatic refunds on failures. Prefer no code? The same models work in ChatGPT and Claude.

Read the full API reference

FAQ

Is this the official Nano Banana API?

No. AiWings is an independent service that runs Nano Banana for you. You use an AiWings key and AiWings credits, with no Google account, Gemini API key or separate billing.

How much does a Nano Banana image cost through the API?

From 5 credits ($0.05) with Nano Banana at 1K, 13 credits ($0.13) with Nano Banana 2 at 2K, and 19 credits ($0.19) with Nano Banana Pro at 2K. Failed images are refunded.

Which Nano Banana should I use?

Nano Banana for quick, low-cost images and edits. Nano Banana 2 for the best quality for the price, up to 4K. Nano Banana Pro when text has to be exact or you need studio-grade detail.

Can I use it from n8n, Make or Zapier?

Yes, any tool that can send an HTTP request works. Send the POST request from Step 3; with "wait": true the response usually already contains the image URL.