Nano Banana API - AI Image & Video Generation API

Authentication

All API requests require an API key passed in the Authorization header:

Authorization: Bearer nb_sk_your_api_key_here

Create and manage your API keys in the API Keys dashboard.

Quick Start

Image Generation

POST

/api/v1/images/generate

Generate an image from a text prompt or reference image.

Request Body

{
  "prompt": "A sunset over mountains",
  "mode": "text",           // "text" | "image"
  "model": "nano-banana",   // optional
  "image_url": "https://...",  // required if mode=image
  "aspect_ratio": "16:9",   // "1:1" | "3:4" | "4:3" | "9:16" | "16:9"
  "resolution": "1K",       // "1K" | "2K" | "4K" (model dependent)
  "num_images": 1,           // 1-4
  "quality": "standard",    // "standard" | "hd"
  "output_format": "png"    // "png" | "jpeg"
}

Response

{
  "success": true,
  "data": {
    "task_id": "clx...",
    "status": "pending",
    "credits_used": 2,
    "credits_remaining": 148
  }
}

Image Status

GET

/api/v1/images/status?task_id=xxx

Check the status of an image generation task. Poll this endpoint until status is 'completed' or 'failed'.

Response

{
  "success": true,
  "data": {
    "task_id": "clx...",
    "status": "completed",
    "progress": 100,
    "image_url": "https://...",
    "completed_at": "2024-01-01T00:00:00Z"
  }
}

Video Generation

POST

/api/v1/videos/generate

Generate a video from a text prompt, optionally with a reference image.

Request Body

{
  "prompt": "A cat walking in a garden",
  "model_id": "veo-3.1-fast",
  "aspect_ratio": "16:9",
  "duration": 8,              // seconds
  "resolution": "720p",       // "720p" | "1080p"
  "image_url": "https://...", // optional reference image
  "generate_audio": true,     // enable audio generation
  "negative_prompt": "..."    // optional
}

Response

{
  "success": true,
  "data": {
    "task_id": "clx...",
    "status": "processing",
    "credits_used": 15,
    "credits_remaining": 133,
    "provider": "wavespeed"
  }
}

Video Status

GET

/api/v1/videos/status?task_id=xxx

Check the status of a video generation task.

Response

{
  "success": true,
  "data": {
    "task_id": "clx...",
    "status": "succeeded",
    "progress": 100,
    "video_url": "https://...",
    "completed_at": "2024-01-01T00:00:00Z"
  }
}

Account Credits

GET

/api/v1/account/credits

Get your current credit balance and subscription status.

Response

{
  "success": true,
  "data": {
    "credits": 148,
    "total_credits": 500,
    "subscription": {
      "plan": "pro",
      "end_date": "2024-12-31T00:00:00Z"
    },
    "is_vip": true
  }
}

Calculate Cost

POST

/api/v1/account/calculate-cost

Preview the credit cost for a generation without executing it.

Request Body

{
  "type": "image",
  "mode": "text",
  "model": "nano-banana-pro",
  "num_images": 2,
  "resolution": "2K"
}

Response

{
  "success": true,
  "data": {
    "type": "image",
    "credits_needed": 16
  }
}

Available Models

GET

/api/v1/models

List all available image and video generation models.

Response

{
  "success": true,
  "data": {
    "image_models": [
      { "id": "nano-banana", "name": "Nano Banana", "is_default": true },
      { "id": "nano-banana-pro", "name": "Nano Banana Pro" },
      ...
    ],
    "video_models": [
      { "id": "veo-3.1-fast", "name": "VEO 3.1 Fast", ... },
      ...
    ]
  }
}

Image Models

model	Name	resolution	aspect_ratio	Base Credits	Subscription
nano-banana	Nano Banana	-	1:1, 3:4, 4:3, 9:16, 16:9	text: 1, image: 2	No
nano-banana-pro	Nano Banana Pro	1K, 2K, 4K	1:1, 3:2, 2:3, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9	6 (+14 for 4K)	No
nano-banana-2	Nano Banana 2	1K, 2K, 4K	1:1, 3:2, 2:3, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9	text: 4, image: 8 (+4 for 2K, +14 for 4K)	Required
seedream4	SeeDream 4	-	1:1, 3:4, 4:3, 9:16, 16:9	4	Required

quality: "standard" | "hd" (hd +2 credits)

num_images: 1 - 4 (total = per-image credits x num_images)

output_format: "png" | "jpeg"

mode: "text" (text-to-image) | "image" (image-to-image, requires image_url)

Video Models

model_id	Name	resolution	aspect_ratio	duration (s)	Audio	Image Input
veo-3.1-fast	VEO 3.1 Fast	720p, 1080p	16:9, 9:16	4, 6, 8	Yes	Yes
veo-3.1	VEO 3.1	720p, 1080p	16:9, 9:16	4, 6, 8	Yes	Yes
seedance-1.5-fast	Seedance 1.5 Fast	720p, 1080p	16:9, 9:16, 1:1	4, 8, 12	Yes	Yes
seedance-1.5	Seedance 1.5 Pro	720p, 1080p	16:9, 9:16, 1:1	4, 8, 12	Yes	Yes
seedance-2.0	Seedance 2.0	480p, 720p	16:9, 9:16, 1:1, 4:3	5, 10, 15	Yes	Yes
wan-2.5	Wan 2.5	480p, 720p, 1080p	16:9, 9:16	5, 10	No	Yes
sora-2	Sora 2	720p	16:9, 9:16	4, 8, 12	Always on	Yes
sora-2-pro	Sora 2 Pro	720p, 1080p	16:9, 9:16	4, 8, 12	Always on	Yes
kling-o3-std	Kling O3	720p	16:9, 9:16, 1:1	5, 10	Yes	Yes
kling-o3-pro	Kling O3 Pro	720p	16:9, 9:16, 1:1	5, 10	Yes	Yes
grok-video	Grok Video	480p, 720p	16:9, 9:16, 1:1	6, 10	No	Yes

Video Credits

Credits vary by model, resolution, duration and audio. Use /api/v1/account/calculate-cost to get the exact cost.

VEO 3.1 Fast (default) — Credits per generation

Resolution	4s	6s	8s
720p (no audio)	10	15	20
720p (with audio)	15	20	30
1080p (no audio)	15	20	25
1080p (with audio)	20	25	35

Error Codes

HTTP Status	Code	Description
401	UNAUTHORIZED	Missing or invalid API key
402	INSUFFICIENT_CREDITS	Not enough credits for this operation
403	FORBIDDEN	API key disabled, expired, or lacks required scope
429	RATE_LIMIT_EXCEEDED	Too many requests per minute
400	INVALID_PROMPT	Prompt is empty or invalid
400	INVALID_MODEL	Unknown model ID
404	TASK_NOT_FOUND	Generation task does not exist
451	CONTENT_FILTERED	Content was rejected by safety filters
500	INTERNAL_ERROR	Server error, please retry

Rate Limits

Default rate limit: 60 requests per minute per API key.

When exceeded, the API returns HTTP 429 with the RATE_LIMIT_EXCEEDED error code.

Response Format

All responses follow a consistent envelope format:

Success

{
  "success": true,
  "data": { ... }
}

Error

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message"
  }
}

Ready to start building?