DEVELOPER API · v1

Images for your application.

A server-to-server API for Nano Banana and GPT Image. Your own API key, your account credits, and asynchronous tasks you can safely poll.

API access, credits and queue policy

Monthly, annual and one-time credit purchases fund the same balance for website and API generation. An active subscription is not required to spend a credit-pack balance. Signed-in accounts can create API keys; generation requires sufficient credits, while model and account queries use the same authenticated API. Anonymous free tasks are not available through this API.

All website and API generation consumes account credits with no site-added waiting delay; provider queues and processing time still apply. HTTP 202 means acceptance, not immediate completion. API rate limits remain enforced.

This is the Nano Banana 2.1 public API, not direct Shyfai access. Use this site's model IDs, local task id and endpoints. Supplier routing, callback_url, request_id and status_url are handled by our backend; do not include supplier parameters or credentials. Application-level callbacks are not exposed in v1.

Compare plans and credit packs

Quick start

  1. Sign in, purchase credits, then create an API key in Developer API keys.
  2. Send one generation request with a unique Idempotency-Key and retain the returned local task ID.
  3. Poll the task approximately every 5 seconds, and save completed result images promptly.

Base URL: https://nanobanana2-1.cc/api/v1

export NANO_API_KEY='YOUR_API_KEY'

curl 'https://nanobanana2-1.cc/api/v1/images/generations' \
  -H "Authorization: Bearer $NANO_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $(python -c 'import uuid; print(uuid.uuid4())')" \
  -d '{
    "model": "gemini-nano-banana-2.1",
    "prompt": "A tiny cafe above the clouds, warm sunset light",
    "size": "16:9",
    "resolution": "2K",
    "quality": "medium"
  }'

Authentication

Send Authorization: Bearer YOUR_API_KEY on every v1 request. These are keys issued by this site, not EvoLink or Google credentials. Full keys are shown only once and can be revoked immediately. Up to 5 active keys per account.

Keys belong on your server. Browser CORS, direct mobile-client access and supplier credential forwarding are not supported. List models with GET /models and check your shared credit balance with GET /account.

Models and credits

Use GET /models for the current capability and credit-cost matrix. All requests generate one image. Nano Banana uses resolution for its upstream quality tier; keep quality set to medium in this unified API. GPT Image has separate quality and resolution settings.

Nano Banana 2.1

gemini-nano-banana-2.1

Resolution: 1K / 2K / 4K
Quality: medium
Reference limit: 14
Aspect ratios: auto, 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 4:5, 5:4, 21:9, 1:4, 4:1, 1:8, 8:1

Prompt-only, medium quality: 1K: 4 credits · 2K: 8 credits · 4K: 13 credits

Nano Banana 2 Lite

gemini-3.1-flash-lite-image

Resolution: 1K
Quality: medium
Reference limit: 14
Aspect ratios: auto, 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 4:5, 5:4, 21:9, 1:4, 4:1, 1:8, 8:1

Prompt-only, medium quality: 1K: 4 credits

Nano Banana 2

gemini-3.1-flash-image-preview

Resolution: 0.5K / 1K / 2K / 4K
Quality: medium
Reference limit: 14
Aspect ratios: auto, 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 4:5, 5:4, 21:9, 1:4, 4:1, 1:8, 8:1

Prompt-only, medium quality: 0.5K: 4 credits · 1K: 4 credits · 2K: 8 credits · 4K: 13 credits

Nano Banana Pro

gemini-3-pro-image-preview

Resolution: 1K / 2K / 4K
Quality: medium
Reference limit: 14
Aspect ratios: auto, 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 4:5, 5:4, 21:9

Prompt-only, medium quality: 1K: 4 credits · 2K: 8 credits · 4K: 13 credits

GPT Image 2.5 Sunburst

gpt-image-2.5-sunburst

Resolution: 1K / 2K / 4K
Quality: low / medium / high / xhigh / max
Reference limit: 16
Aspect ratios: 1:1, 1:2, 2:1, 1:3, 3:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 9:21, 21:9

Prompt-only, medium quality: 1K: 2 credits · 2K: 3 credits · 4K: 4 credits

GPT Image 2.5 Flare

gpt-image-2.5-flare

Resolution: 1K / 2K / 4K
Quality: low / medium / high / xhigh / max
Reference limit: 16
Aspect ratios: 1:1, 1:2, 2:1, 1:3, 3:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 9:21, 21:9

Prompt-only, medium quality: 1K: 2 credits · 2K: 3 credits · 4K: 4 credits

Nano Banana adds one product credit per reference. GPT Image keeps its existing zero/one-reference price and adds one product credit for each reference beyond the first as a planning policy, not a provider token quote. Credits are reserved atomically when a task is accepted and refunded on confirmed failure. Temporary polling errors are not confirmed failures. This API does not provide unlimited generations or an automatic paid retry.

Reference image uploads

POST /uploads with multipart/form-data and one file field per request. Supported: JPG, PNG and WebP, up to 10 MB per file. Upload each reference separately, then pass the returned URLs in image_urls: up to 14 for Nano Banana or 16 for GPT Image. Every URL must belong to the same account; external URLs and duplicates are rejected.

curl 'https://nanobanana2-1.cc/api/v1/uploads' \
  -H "Authorization: Bearer $NANO_API_KEY" \
  -F 'file=@reference.png'

Create a generation

POST /images/generations · Content-Type: application/json

prompt
Required, non-empty. Nano Banana 2.1: up to 4,000 Unicode characters as a conservative app limit; other Nano models: 2,000; GPT Image: 32,000.
model
Optional. Default: gemini-nano-banana-2.1. Use a model ID returned by /models.
size / resolution / quality
Choose supported values from /models. This public API accepts each model's supported aspect ratios (including auto for Nano models), not explicit pixel sizes. Lite is 1K only.
image_urls
Optional ordered array of owned uploaded URLs: Nano Banana up to 14, GPT Image up to 16. Omit or use [] for text-to-image. The full list is forwarded in order; changing its order or any URL conflicts under the same Idempotency-Key. Generation history currently stores only the first reference URL.
Idempotency-Key
Required request header, 8–128 safe characters. Prefer a UUID and persist it before the request. Reuse the same key and same body on uncertain retries.

HTTP 202 returns the local task id, status and credits_used. A repeated logical request must not use a new Idempotency-Key. The same key with a different body returns 409. If submission remains uncertain, retain the key and contact support instead of creating another paid task.

Unsupported in v1: masks, transparent output, output-format selection, multiple output images, search grounding and callbacks. Unsupported fields are rejected rather than silently ignored.

Query a task

GET /tasks/{id}, using the local id returned by generation creation. Only your own tasks are accessible. States: processing, uncertain, completed, failed. On completion, results contains objects with a url field. An uncertain status means provider acceptance could not be confirmed: credits stay reserved and support must reconcile the task; never submit it again with a new key. Download important results promptly; provider fallback URLs may expire after 24 hours.

curl 'https://nanobanana2-1.cc/api/v1/tasks/LOCAL_TASK_ID' \
  -H "Authorization: Bearer $NANO_API_KEY"

Errors and limits

Errors use { error: { code, message } }. Handle 400 for invalid settings, 401 for invalid/revoked keys, 402 for insufficient credits, 404 for inaccessible tasks, 409 for an idempotency conflict, 413 for oversized input, 429 for rate limiting, and 5xx for temporary service failures.

Limits are shared per account across API keys: 60 requests/minute, with at most 10 generation submissions/minute. Respect Retry-After on 429. Poll approximately every 5 seconds, not in a tight loop. New keys do not reset limits.

Server-side examples

Node.js

// Node.js 20+; run on your server, not in browser JavaScript.
const base = 'https://nanobanana2-1.cc/api/v1';
const headers = { Authorization: 'Bearer ' + process.env.NANO_API_KEY };
const requestKey = crypto.randomUUID(); // Persist this key before submitting.
const response = await fetch(base + '/images/generations', {
  method: 'POST',
  headers: { ...headers, 'Content-Type': 'application/json', 'Idempotency-Key': requestKey },
  body: JSON.stringify({ model: 'gpt-image-2.5-sunburst', prompt: 'A minimal botanical illustration', size: '1:1', resolution: '1K', quality: 'medium' })
});
const task = await response.json();
if (!response.ok) throw new Error(JSON.stringify(task.error));
// Retry uncertain submissions with the SAME requestKey and SAME request body.
for (let attempt = 0; attempt < 120; attempt++) {
  await new Promise(resolve => setTimeout(resolve, 5000));
  const status = await fetch(base + '/tasks/' + encodeURIComponent(task.id), { headers });
  if (status.status === 429 || status.status >= 500) continue;
  const result = await status.json();
  if (!status.ok) throw new Error(JSON.stringify(result.error));
  if (result.status === 'failed') throw new Error(JSON.stringify(result.error));
  if (result.status === 'completed') { console.log(result.results); break; }
  if (attempt === 119) console.log('Still processing. Keep task.id and resume polling later.');
}

Python

import os, uuid, time, json, urllib.request, urllib.error

base = 'https://nanobanana2-1.cc/api/v1'
key = os.environ['NANO_API_KEY']
request_key = str(uuid.uuid4())  # Persist before submission; reuse on uncertain retries.
body = json.dumps({'prompt': 'A cozy reading room in warm light', 'size': '4:3', 'resolution': '1K', 'quality': 'medium'}).encode()
request = urllib.request.Request(base + '/images/generations', data=body, headers={
    'Authorization': 'Bearer ' + key, 'Content-Type': 'application/json', 'Idempotency-Key': request_key
})
with urllib.request.urlopen(request, timeout=90) as response:
    task = json.load(response)
for _ in range(120):
    time.sleep(5)
    poll = urllib.request.Request(base + '/tasks/' + task['id'], headers={'Authorization': 'Bearer ' + key})
    try:
        with urllib.request.urlopen(poll, timeout=30) as response:
            result = json.load(response)
    except urllib.error.HTTPError as error:
        if error.code == 429 or error.code >= 500:
            continue
        raise
    if result['status'] == 'failed':
        raise RuntimeError(result.get('error'))
    if result['status'] == 'completed':
        print(result['results'])
        break
else:
    print('Still processing. Save task ID and resume polling later:', task['id'])

Store both the request key and returned task ID in your application database. These samples use bounded polling; production clients should also add timeouts, backoff and durable task recovery.

Nano Banana 2.1 API Docs — Authentication, Image Generation & Tasks