Nano Banana API

Generate AI images and videos programmatically. Simple REST API with credit-based billing.

RESTful API
Async Generation
Multiple Models

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

modelNameresolutionaspect_ratioBase CreditsSubscription
nano-bananaNano Banana-1:1, 3:4, 4:3, 9:16, 16:9text: 1, image: 2
No
nano-banana-proNano Banana Pro1K, 2K, 4K1:1, 3:2, 2:3, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:96 (+14 for 4K)
No
nano-banana-2Nano Banana 21K, 2K, 4K1:1, 3:2, 2:3, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9text: 4, image: 8 (+4 for 2K, +14 for 4K)
Required
seedream4SeeDream 4-1:1, 3:4, 4:3, 9:16, 16:94
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_idNameresolutionaspect_ratioduration (s)AudioImage Input
veo-3.1-fastVEO 3.1 Fast720p, 1080p16:9, 9:164, 6, 8YesYes
veo-3.1VEO 3.1720p, 1080p16:9, 9:164, 6, 8YesYes
seedance-1.5-fastSeedance 1.5 Fast720p, 1080p16:9, 9:16, 1:14, 8, 12YesYes
seedance-1.5Seedance 1.5 Pro720p, 1080p16:9, 9:16, 1:14, 8, 12YesYes
seedance-2.0Seedance 2.0480p, 720p16:9, 9:16, 1:1, 4:35, 10, 15YesYes
wan-2.5Wan 2.5480p, 720p, 1080p16:9, 9:165, 10NoYes
sora-2Sora 2720p16:9, 9:164, 8, 12Always onYes
sora-2-proSora 2 Pro720p, 1080p16:9, 9:164, 8, 12Always onYes
kling-o3-stdKling O3720p16:9, 9:16, 1:15, 10YesYes
kling-o3-proKling O3 Pro720p16:9, 9:16, 1:15, 10YesYes
grok-videoGrok Video480p, 720p16:9, 9:16, 1:16, 10NoYes

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

Resolution4s6s8s
720p (no audio)101520
720p (with audio)152030
1080p (no audio)152025
1080p (with audio)202535

Error Codes

HTTP StatusCodeDescription
401
UNAUTHORIZEDMissing or invalid API key
402
INSUFFICIENT_CREDITSNot enough credits for this operation
403
FORBIDDENAPI key disabled, expired, or lacks required scope
429
RATE_LIMIT_EXCEEDEDToo many requests per minute
400
INVALID_PROMPTPrompt is empty or invalid
400
INVALID_MODELUnknown model ID
404
TASK_NOT_FOUNDGeneration task does not exist
451
CONTENT_FILTEREDContent was rejected by safety filters
500
INTERNAL_ERRORServer 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?