Nano Banana API Documentation

Programmatically generate AI images via REST API. Supports text-to-image, image-to-image, and three request modes: sync, stream, and async.

1. Quick Start

Step 1: Get an API Key

Go to Settings -> API Keys on the website to create an API Key.

Step 2: Send a Request

curl -X POST https://www.nananobanana.com/api/v1/generate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer nb_your_api_key_here" \
  -d '{
    "prompt": "A cute orange cat sitting on a windowsill",
    "selectedModel": "nano-banana"
  }'

2. Authentication

All API requests require an API Key in the HTTP Header:

Authorization: Bearer nb_your_api_key_here

WARNING

⚠️ The API Key is only displayed once when created. Please keep it safe. Each user can create up to 5 API Keys.

3. Base URL

https://www.nananobanana.com/api/v1

4. Generate Endpoint

POST /api/v1/generate

Generate an image. Supports text-to-image and image-to-image modes, with three request modes.

Request Parameters

Parameter	Type	Required	Description
prompt	string	✓	Image generation prompt
selectedModel	string	-	Model name, defaults to "nano-banana"
referenceImageUrls	string[]	*	Reference image URL array (required for image-to-image)
aspectRatio	string	-	Aspect ratio, defaults to "default"
quantity	number	-	Number of images per call, defaults to 1, range 1–backend limit (default max 4)
mode	string	-	Request mode: "sync" (default), "stream", "async"

TIP

The system automatically determines the generation type (text-to-image / image-to-image) based on whether referenceImageUrls is provided.

About quantity (batch generation)

• The value is clamped to 1–backend limit (default max 4); out-of-range values are truncated automatically.
• Credits scale with the count: total = unit cost × quantity (image-to-image extra-image fees are included in the unit cost).
• Streaming models emit a single image per call, so quantity is forced to 1.
• When quantity > 1, results are returned as arrays (imageUrls / outputImageUrls contain multiple URLs).

Three Request Modes

Choose the request mode that best fits your use case:

Feature	Sync sync	Stream stream	Async async
Response	Wait for completion	SSE real-time push	Immediate return, poll for result
Progress feedback	❌	✅	❌
Best for	Simple integrations, scripts	Frontend real-time display	Batch tasks, background processing
Timeout risk	Higher (waits for completion)	Lower (persistent connection)	None (returns immediately)
Complexity	⭐	⭐⭐	⭐⭐

👉 See detailed documentation and code examples for each mode:

• Sync Mode — Simplest integration
• Stream Mode — Real-time progress updates
• Async Mode — Background processing with polling

GET /api/v1/generate

Query the status and result of a generation record. Typically used with async mode.

Query Parameters

Parameter	Type	Description
id	string	Generation record ID

Response

{
  "data": {
    "id": "clxx...",
    "prompt": "...",
    "outputImageUrls": ["https://..."],
    "modelUsed": "nano-banana",
    "processingStatus": "completed",
    "creditsUsed": 1,
    "createdAt": "2025-01-01T00:00:00.000Z"
  }
}

processingStatus Values

Status	Description
processing	Generation in progress
completed	Generation complete, outputImageUrls contains result images
failed	Generation failed, errorMessage contains error details

---

5. Other Endpoints

GET /api/v1/models

Get the list of available image generation models. No authentication required.

Response

{
  "data": [
    {
      "name": "nano-banana",
      "displayName": "Nano Banana",
      "creditsCost": 1,
      "supportsImageInput": true,
      "supportsAspectRatio": true,
      "requiresPro": false
    }
  ]
}

---

GET /api/v1/credits

Query the current account's available credit balance.

Response

{
  "data": {
    "credits": 100
  }
}

6. Common Error Responses

Status Code	Description
400 Bad Request	Invalid request parameters (e.g., missing prompt, invalid mode value)
401 Unauthorized	Invalid or missing API Key
402 Payment Required	Insufficient credits
403 Forbidden	API access is not enabled for the account
429 Too Many Requests	Account concurrency limit exceeded (each account allows only 1 concurrent request by default)
500 Internal Server Error	Internal server error
503 Service Unavailable	Server busy (async mode only)

429 concurrency limit response example

The number of concurrent API requests per account is limited (default 1, adjustable by the backend). When exceeded, it returns:

{
  "error": "Too many concurrent API requests for this account",
  "type": "concurrency_limit",
  "limit": 1,
  "active": 1
}

The response carries Retry-After, X-RateLimit-Limit, and X-RateLimit-Active headers for backoff.

7. Important Notes

• API calls do not perform safety keyword checks. Please ensure your input content is compliant.
• Credits consumed per generation depend on the selected model. The default model costs 1 credit.
• In image-to-image mode, each additional reference image costs 1 extra credit.
• Use quantity to generate multiple images per call; credits scale with the count, while streaming models are fixed to 1 image.
• The number of concurrent API requests per account is limited (default 1, adjustable by the backend); exceeding it returns 429.
• Generated image URLs are valid for 15 days. Please download and save them promptly.
• Each user can create up to 5 API Keys.
• API access must be enabled for your account (automatically enabled when cumulative recharge exceeds ¥1000, or contact admin for manual activation).

8. Contact Us

For API integration questions, please reach out to us:

• 📧 API Support: [email protected]
• 📧 API Support: [email protected]