nanobananas-api-guide

name	nanobananas-api-guide
description	Complete guide for using the NanoBananas.AI API — image generation, video generation, pricing, authentication, and code examples in Python/Node.js/cURL. Use when building apps with NanoBananas API, checking pricing, or troubleshooting API errors.

NanoBananas.AI API Guide

Your complete reference for building with the NanoBananas.AI API. Generate images and videos using state-of-the-art AI models.

Base URL: https://nanobananas.ai Documentation: https://nanobananas.ai/api

---

Authentication

All API requests require an API key via header:

Authorization: Bearer YOUR_API_KEY

Get your API key at: https://nanobananas.ai/api-keys

Requirement: Advanced subscription plan ($29.90/month or $269.90/year)

---

Quick Start

Generate an Image (30 seconds)

curl -X POST "https://nanobananas.ai/api/v1/images/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "prompt=A golden retriever playing in autumn leaves, cinematic lighting"

Generate a Video (2-5 minutes)

# Step 1: Submit task
curl -X POST "https://nanobananas.ai/api/v1/video/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A cat playing with a ball in slow motion", "model": "veo3"}'

# Step 2: Poll status (use task_id from step 1)
curl "https://nanobananas.ai/api/v1/video/status?task_id=YOUR_TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

---

Image Generation

POST /api/v1/images/generate

Supports multipart/form-data and application/json.

Parameter	Type	Required	Description
prompt	string	Yes*	Image description (max 5000 chars, returns HTTP 400 if exceeded)
model	string	No	Model ID, default gemini-2.5-flash-image-preview
image	File/File[]	No	Reference image file(s) for img2img
imageUrl	string/string[]	No	Reference image URL(s) for img2img
aspectRatio	string	No	See aspect ratio table below
img_size	string	No	1k / 2k / 4k, default 1k
mode	string	No	txt2img or img2img (auto-detected if omitted)
hdPro	string	No	Pass "true" for HD mode
googleSearch	string	No	"true" to enable search enhancement (Nano Banana 2 only)

*Either prompt or image/imageUrl must be provided

Supported Image Models

Model ID	Name	1k	2k	4k	Notes
gemini-2.5-flash-image-preview	Nano Banana	10	15	-	Default, fastest
gemini-3.1-pro-image-preview	Nano Banana 2	25	35	60	Better quality, extended aspect ratios
gemini-3-pro-image-preview	Nano Banana Pro	30	50	80	Highest quality
gemini-3-pro-image-preview-vip	Nano Banana Pro VIP	40	60	90	Dedicated stable channel
sora_image	GPT-4o	10	-	-	OpenAI model

Aspect Ratios

All models: auto, 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3

Nano Banana 2 additionally supports: 4:1, 1:4, 8:1, 1:8

Output Dimensions (img_size)

img_size	1:1	16:9	9:16
1k	~1024x1024	~1280x720	~720x1280
2k	~2048x2048	~2560x1440	~1440x2560
4k	~4096x4096	~3840x2160	~2160x3840

img_size only applies to Nano Banana 2 / Pro / Pro VIP models.

Image Response (200)

{
  "status": 200,
  "images": ["https://img.nanobananas.ai/xxx.webp"],
  "uuid": "abc123-def456",
  "prompt": "A golden retriever...",
  "credits": { "remaining": 4500, "costCredits": 10 }
}

---

Async Image Generation (Recommended for Production)

POST /api/v1/images/async

Same parameters as /api/v1/images/generate. Returns immediately with a task_id.

{
  "status": 202,
  "task_id": "abc123-def456",
  "message": "Task submitted. Use GET /api/v1/images/task-status?task_id={task_id} to poll."
}

GET /api/v1/images/task-status?task_id=xxx

Poll until status is completed or failed.

---

Video Generation

POST /api/v1/video/generate

Parameter	Type	Required	Description
prompt	string	Yes	Video description (max 1500 chars)
model	string	No	veo3 (default), sora2, seedance
aspect_ratio	string	No	16:9, 9:16, 1:1
resolution	string	No	480p, 720p, 1080p
duration	number	No	Seconds (model-dependent)
image_url	string/string[]	No	Reference image(s) for img2video
image_file	File (repeatable)	No	Upload reference files (form-data)
veo3_mode	string	No	fast or pro (Veo3 only)
seedance_version	string	No	1.0-pro, 1.5-pro, 2.0-pro

Video Models & Pricing

Veo 3.1

Mode	Duration	Credits	Est. USD
Fast	8s	150	~$0.19
Pro	8s	750	~$0.94

Seedance 1.0 Pro

Duration	480p	720p	1080p
5s	30	60	120
10s	60	100	200

Seedance 1.5 Pro (audio supported)

Duration	Credits
5s	120
10s	240
12s	360

Seedance 2.0 Pro (audio + multi-image, up to 5)

Duration	Credits
15s	1200

Sora 2

Version	Resolution	10s	15s
Stable	720p	180	360
Standard	1080p	600	900

Video Response (202)

{
  "success": true,
  "data": {
    "task_id": "abc123-def456",
    "status": "pending",
    "credits_used": 150,
    "estimated_time": "2-5 minutes"
  }
}

GET /api/v1/video/status?task_id=xxx

Poll until status is completed:

{
  "success": true,
  "data": {
    "task_id": "abc123-def456",
    "status": "completed",
    "video_url": "https://video.nanobananas.ai/xxx.mp4",
    "progress": 100
  }
}

---

Code Examples

Python — Generate Image

import requests

API_KEY = "YOUR_API_KEY"
API_URL = "https://nanobananas.ai/api/v1/images/generate"

response = requests.post(API_URL, headers={
    "Authorization": f"Bearer {API_KEY}"
}, data={
    "prompt": "A futuristic city at sunset, cyberpunk style",
    "model": "gemini-3-pro-image-preview",
    "aspectRatio": "16:9",
    "img_size": "2k"
})

result = response.json()
if result["status"] == 200:
    print(f"Image: {result['images'][0]}")
    print(f"Credits remaining: {result['credits']['remaining']}")

Python — Generate Video with Polling

import requests, time

API_KEY = "YOUR_API_KEY"
BASE = "https://nanobananas.ai/api/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

# Submit
resp = requests.post(f"{BASE}/video/generate", headers=HEADERS, json={
    "prompt": "A drone flying over a mountain landscape",
    "model": "veo3",
    "veo3_mode": "fast"
})
task_id = resp.json()["data"]["task_id"]
print(f"Task submitted: {task_id}")

# Poll
while True:
    status_resp = requests.get(f"{BASE}/video/status?task_id={task_id}", headers=HEADERS)
    data = status_resp.json()["data"]
    print(f"Status: {data['status']} | Progress: {data.get('progress', 0)}%")
    if data["status"] == "completed":
        print(f"Video URL: {data['video_url']}")
        break
    elif data["status"] == "failed":
        print(f"Failed: {data.get('error')}")
        break
    time.sleep(10)

Node.js — Generate Image

const response = await fetch("https://nanobananas.ai/api/v1/images/generate", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    prompt: "A beautiful watercolor painting of a Japanese garden",
    model: "gemini-3.1-pro-image-preview",
    aspectRatio: "1:1",
    img_size: "2k"
  })
});

const result = await response.json();
console.log("Image URL:", result.images[0]);

cURL — Image-to-Image with File Upload

curl -X POST "https://nanobananas.ai/api/v1/images/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "prompt=Transform this photo into an oil painting style" \
  -F "image=@photo.jpg" \
  -F "model=gemini-3-pro-image-preview" \
  -F "img_size=2k"

cURL — Seedance Video with Reference Image

curl -X POST "https://nanobananas.ai/api/v1/video/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "The woman walks gracefully along the beach at sunset",
    "model": "seedance",
    "seedance_version": "1.0-pro",
    "duration": 5,
    "resolution": "480p",
    "image_url": "https://example.com/reference.jpg"
  }'

cURL — Seedance 2.0 with Multiple Files

curl -X POST "https://nanobananas.ai/api/v1/video/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "prompt=Use @1 as opening scene, transition to @2 setting" \
  -F "model=seedance" \
  -F "seedance_version=2.0-pro" \
  -F "aspect_ratio=16:9" \
  -F "image_file=@scene1.jpg" \
  -F "image_file=@scene2.jpg" \
  -F "image_file=@background_music.mp3"

---

Pricing Plans

Plan	Price (USD)	Credits	Per 10 Credits
Professional Monthly	$9.90/mo	3,800	$0.026
Advanced Monthly	$29.90/mo	18,000	$0.017
Professional Annual	$89.90/yr	45,600	$0.020
Advanced Annual	$269.90/yr	216,000	$0.012
One-Time Standard	$12.90	4,560	$0.028
One-Time Professional	$29.90	10,565	$0.028
One-Time Advanced	$69.90	24,700	$0.028
Large $200	$200	120,000 (+20%)	$0.017
Large $500	$500	337,500 (+35%)	$0.015
Large $1000	$1,000	800,000 (+60%)	$0.013

Failed tasks are never charged. Credits are refunded automatically.

---

Error Handling

Code	Meaning	Action
200	Success	Parse result
202	Task submitted (video)	Poll for status
400	Bad request / Prompt too long	Check parameters
401	Invalid API key	Check Authorization header
402	Insufficient credits	Top up credits
403	No API permission	Upgrade to Advanced plan
429	Rate limited	Wait and retry (check Retry-After header)
500	Server error	Retry after a few seconds

---

Rate Limits

Check response headers:

• X-RateLimit-Limit — Max requests per minute
• X-RateLimit-Remaining — Remaining requests
• X-RateLimit-Reset — Seconds until reset

---

Tips

1. Use async API for production — /api/v1/images/async is more stable than sync
2. Poll with 5-10s intervals — Don't hammer the status endpoint
3. Nano Banana 2 for wide/tall images — Only model supporting 4:1, 1:4, 8:1, 1:8
4. Seedance 1.0 Pro for budget video — 480p 5s costs only 30 credits (~$0.04)
5. Annual plans save 25% — Advanced Annual is the best value at $0.012 per 10 credits
6. Google Search enhancement — Add "googleSearch": "true" with Nano Banana 2 for real-time context