Nano Banana API User Guide

A practical guide to understanding and using the Nano Banana API effectively.

Table of Contents

• Getting Started
• Understanding Authentication
• Choosing the Right Endpoint
• Choosing the Right Model
• Feature Guide
• Image Input Guidelines
• Response Formats
• Best Practices
• Common Use Cases
• Error Handling
• Troubleshooting
• FAQ

Getting Started

What You Need

Before you begin using the Nano Banana API, make sure you have:

1. An HTTP Client - Any tool that can make HTTP requests, such as cURL, Postman, Bruno, Insomnia, or your application
2. A Prompt or Source Image - Use a text prompt for generation, and an image URL, base64 image, or uploaded file for edits and upscaling
3. The API Base URL - All requests should be sent to https://nanobanana.aikit.club

First Steps

1. List Available Models: Use /v1/models to confirm the API is reachable
2. Make Your First Generation Request: Use /v1/images/generations with a text prompt
3. Try Image Editing: Use /v1/images/edits with an existing image and edit instruction
4. Upscale an Image: Use /v1/images/upscale with x2 or x4
5. Display the Result: Use the returned image URL or base64 image data in your app

API Base URL

All API requests should be sent to:

https://nanobanana.aikit.club

Quick Health Check

curl https://nanobanana.aikit.club/v1/models

Expected response:

{
  "object": "list",
  "data": [
    {
      "id": "nano-banana",
      "object": "model",
      "created": 1764671202,
      "owned_by": "google"
    },
    {
      "id": "imagen-4.0-upscale-preview",
      "object": "model",
      "created": 1764671202,
      "owned_by": "google"
    }
  ]
}

Understanding Authentication

Does Nano Banana API Need an API Key?

The current public Nano Banana API OpenAPI definition does not define a required authentication scheme. The public endpoints can be called directly over HTTPS.

If you deploy your own protected version later, you can add standard bearer-token authentication:

Security Tips

• Store private deployment keys in environment variables
• Never commit secrets to version control
• Use HTTPS only
• Do not expose private API keys in browser code
• Validate authentication on your own server or worker if you add protected access

Choosing the Right Endpoint

Quick Endpoint Selector

Need to create a new image from text? Use POST /v1/images/generations.

Need a shareable or browser-testable generation URL? Use GET /v1/images/generations.

Need to modify an existing image? Use POST /v1/images/edits.

Need to edit an image that is already available at a public URL? Use GET /v1/images/edits.

Need to increase image resolution? Use POST /v1/images/upscale.

Need quick URL-based upscaling? Use GET /v1/images/upscale.

Need to verify supported model IDs? Use GET /v1/models.

Endpoint Overview

Choosing the Right Model

Quick Model Selector

Need image generation? Use nano-banana.

Need image editing? Use nano-banana.

Need image upscaling? Use /v1/images/upscale, which uses the worker upscale backend exposed as imagen-4.0-upscale-preview.

Model Overview

Feature Guide

1. Image Generation

What it does: Creates one or more images from a text prompt.

Endpoint: POST /v1/images/generations

Required fields:

• prompt - Text prompt for the image, 1 to 4096 characters

Optional fields:

• model - Only nano-banana
• n - Number of images, from 1 to 4
• aspect_ratio - 1:1, 16:9, 9:16, 3:4, or 4:3
• size - Legacy OpenAI-compatible size parameter
• output_format - jpeg, png, or webp
• response_format - url or b64_json

curl -X POST https://nanobanana.aikit.club/v1/images/generations \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A cinematic product photo of a golden banana on a marble table",
    "model": "nano-banana",
    "n": 1,
    "aspect_ratio": "1:1",
    "output_format": "png",
    "response_format": "url"
  }'

Tips:

• Be specific about subject, style, lighting, mood, composition, and camera angle
• Use aspect_ratio for new integrations
• Use n up to 4 when you want variations
• Use webp for smaller web assets, png for crisp graphics, and jpeg for photo-like output

2. Image Generation with GET

What it does: Generates images using query parameters.

Endpoint: GET /v1/images/generations

curl "https://nanobanana.aikit.club/v1/images/generations?prompt=A%20serene%20mountain%20landscape%20at%20sunset&aspect_ratio=16:9&output_format=png&response_format=url"

When to use:

• Simple tests
• Browser demos
• Short prompts

When to prefer POST:

• Longer prompts
• Production apps
• File or base64 workflows
• Cleaner request bodies

3. Image Editing

What it does: Modifies an existing image using text instructions.

Endpoint: POST /v1/images/edits

Required fields:

• prompt - Instruction for editing the image
• image - Image URL, data URL base64 string, raw base64 string, or uploaded file

Optional fields:

• model - Only nano-banana
• n - Number of edited images, from 1 to 4
• aspect_ratio - 1:1, 16:9, 9:16, 3:4, or 4:3
• size - Legacy OpenAI-compatible size parameter
• response_format - url or b64_json

curl -X POST https://nanobanana.aikit.club/v1/images/edits \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Add soft golden sunset lighting and a rainbow in the sky",
    "image": "https://example.com/image.png",
    "model": "nano-banana",
    "n": 1,
    "aspect_ratio": "1:1",
    "response_format": "url"
  }'

Tips:

• Give direct, specific edit instructions
• Use one major edit per request when precision matters
• Use source images with visible subjects and good lighting
• Use file upload or base64 when the image is not publicly accessible

4. Image Editing with GET

What it does: Edits an image using query parameters.

Endpoint: GET /v1/images/edits

Important: GET edit requests require the image to be available as a URL.

curl "https://nanobanana.aikit.club/v1/images/edits?prompt=Add%20a%20rainbow%20in%20the%20sky&image=https%3A%2F%2Fexample.com%2Fimage.png&response_format=url"

5. Image Upscaling

What it does: Increases image resolution using the worker upscale backend.

Endpoint: POST /v1/images/upscale

Required fields:

• image - Image URL, data URL base64 string, raw base64 string, or uploaded file

Optional fields:

• upscale_factor - x2 or x4
• response_format - url or b64_json

curl -X POST https://nanobanana.aikit.club/v1/images/upscale \
  -H "Content-Type: application/json" \
  -d '{
    "image": "https://example.com/image.png",
    "upscale_factor": "x4",
    "response_format": "url"
  }'

Tips:

• Use x2 for faster enhancement
• Use x4 when you need a larger final image
• Upscaling works best on clean source images
• Upscale the final edited image when building a multi-step workflow

6. Image Upscaling with GET

What it does: Upscales an image URL using query parameters.

Endpoint: GET /v1/images/upscale

curl "https://nanobanana.aikit.club/v1/images/upscale?image=https%3A%2F%2Fexample.com%2Fimage.png&upscale_factor=x2&response_format=url"

7. MCP Documentation Access

What it does: Allows AI tools such as Cursor, Windsurf, and Claude Desktop to access Nano Banana API documentation through a remote MCP server.

MCP URL:

https://nano-banana-api.readme.io/mcp

Example configuration:

{
  "mcpServers": {
    "nano-banana-api": {
      "url": "https://nano-banana-api.readme.io/mcp"
    }
  }
}

Image Input Guidelines

Supported Image Inputs

For edit and upscale requests, images can be provided as:

• URL - A direct public image URL
• Data URL base64 - Example: data:image/png;base64,...
• Raw base64 - Base64 image bytes as a string
• File upload - Multipart form-data upload using the field name image

Supported MIME Types

• image/jpeg
• image/jpg
• image/png
• image/gif
• image/webp
• image/bmp

GET vs POST Inputs

Aspect Ratio and Legacy Size

Nano Banana prefers aspect_ratio, but the API also accepts OpenAI-compatible size values.

Response Formats

URL Response

Use response_format: "url" when you want a worker-hosted image URL.

{
  "created": 1764671202,
  "data": [
    {
      "url": "https://nanobanana.aikit.club/images/130708-24112025_abcd_generate.png",
      "revised_prompt": "A serene mountain landscape at sunset"
    }
  ]
}

Base64 Response

Use response_format: "b64_json" when you want image bytes that your application can store or process directly.

{
  "created": 1764671202,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAAA...",
      "revised_prompt": "A serene mountain landscape at sunset"
    }
  ]
}

Choosing a Response Format

Use url when:

• You want the simplest integration
• You are displaying images in a web app
• You want a downloadable hosted image

Use b64_json when:

• You want to store images in your own storage
• You need to process image bytes immediately
• You do not want to depend on hosted image URLs

Best Practices

Prompt Writing

For generation:

• Describe the main subject first
• Add style, mood, lighting, colors, and composition
• Mention camera angle or framing when it matters
• Avoid vague prompts like make it better

For editing:

• Use direct instructions
• Mention what should be preserved if important
• Make one major change at a time for better control
• Identify the target area when editing a specific part of the image

Request Optimization

Use POST for production:

• Cleaner payloads
• Better for long prompts
• Supports files and base64 inputs
• Easier to extend later

Use GET for quick tests:

• Easy browser testing
• Simple demos
• Short prompts
• Public image URLs

Reliability

• Validate required fields before sending requests
• Retry temporary 500 and 504 errors with backoff
• Do not retry 400 errors without changing the request
• Store revised_prompt if you want reproducible image history

Common Use Cases

1. Building an Image Generator

Goal: Let users create images from prompts.

Steps:

1. Collect a prompt
2. Let users choose aspect ratio and output format
3. Call /v1/images/generations
4. Display the returned image URL
5. Save the image URL and revised prompt

Best practices:

• Limit prompt length to 4096 characters
• Allow up to 4 variations with n
• Show loading states
• Provide download controls

2. Building an Image Editor

Goal: Let users upload or link an image and modify it with text.

Steps:

1. Accept an image URL or file upload
2. Collect a clear edit instruction
3. Call /v1/images/edits
4. Show before and after images
5. Let users continue editing the result

Best practices:

• Use multipart form-data for local uploads
• Keep edit instructions specific
• Store original and edited image URLs
• Add a before/after comparison UI

3. Building an Upscaler

Goal: Improve image resolution.

Steps:

1. Accept an image URL, base64 image, or file upload
2. Let users choose x2 or x4
3. Call /v1/images/upscale
4. Display and download the upscaled image

Best practices:

• Default to x2
• Use x4 for final export workflows
• Warn users that larger upscales can take longer
• Upscale after final edits for best workflow quality

4. OpenAI-Compatible Image Integration

Goal: Use familiar /v1/images/* endpoints in an existing app.

Steps:

1. Set the base URL to https://nanobanana.aikit.club
2. Use /v1/images/generations for prompt-to-image
3. Use /v1/images/edits for image edits
4. Use /v1/models to verify model IDs

Best practices:

• Prefer aspect_ratio over legacy size
• Keep model as nano-banana for generate and edit
• Use response_format: "url" unless you need image bytes

Error Handling

Error Response Structure

Error responses follow this format:

{
  "error": {
    "message": "Missing or invalid required parameter: prompt",
    "type": "invalid_request_error",
    "param": null,
    "code": null
  }
}

Common Errors and Solutions

Invalid Request (400)

Symptoms: Missing prompt, missing image, invalid parameter, or unsupported value.

Solutions:

• Check all required fields
• Use supported values for aspect_ratio, output_format, and upscale_factor
• Ensure n is between 1 and 4
• Use a valid public image URL for GET edit and upscale requests

Image Not Found (404)

Symptoms: Hosted image URL no longer exists or filename is invalid.

Solutions:

• Check the /images/{filename} URL
• Store important images in your own storage if permanence matters
• Regenerate or re-upload the image

Server Error (500)

Symptoms: Internal server or upstream model error.

Solutions:

• Retry after a short delay
• Try a simpler prompt
• Use a cleaner source image
• Log the payload for debugging

Timeout (504)

Symptoms: Server polling timeout.

Solutions:

• Retry with exponential backoff
• Try n: 1
• Use a smaller or cleaner source image
• Prefer file upload or URL over very large base64 payloads

Retry Strategy

Retry:

• Network failures
• 500 errors
• 504 timeouts

Do not retry without changes:

• 400 invalid request errors
• Invalid image URLs
• Unsupported parameter values

Recommended retry timing:

1 second -> 2 seconds -> 4 seconds -> stop and show the error

Troubleshooting

Image Generation Fails

Diagnostic steps:

1. Confirm prompt is not empty
2. Confirm model is nano-banana
3. Confirm n is between 1 and 4
4. Confirm aspect_ratio is one of 1:1, 16:9, 9:16, 3:4, 4:3
5. Try a shorter and clearer prompt

Image Editing Fails

Diagnostic steps:

1. Confirm both prompt and image are present
2. If using GET, confirm image is a public URL
3. If using upload, confirm the field name is image
4. Confirm the MIME type is supported
5. Try a simple edit instruction first

Upscaling Fails

Diagnostic steps:

1. Confirm image is present
2. Confirm upscale_factor is x2 or x4
3. Try x2 before x4
4. Use a clean image URL or multipart upload
5. Retry after a delay if the response is 504

Base64 Response Does Not Render

Diagnostic steps:

1. Check whether the returned value includes a data:image/...;base64, prefix
2. If it is raw base64, add the correct data URL prefix before using it in an <img> tag
3. Confirm the decoded data is valid image bytes

const src = image.b64_json.startsWith("data:")
  ? image.b64_json
  : `data:image/png;base64,${image.b64_json}`;

GET URL Does Not Work

Diagnostic steps:

1. URL-encode the prompt
2. URL-encode the image URL
3. Keep query strings short
4. Use POST if the prompt or image input is long

FAQ

General Questions

Q: What is Nano Banana API used for?

A: It is an OpenAI-compatible image API for generating images, editing existing images, and upscaling image resolution.

Q: What is the base URL?

A: https://nanobanana.aikit.club

Q: Does it support chat completions?

A: No. This API is focused on image generation, image editing, image upscaling, and model listing.

Q: Is the API OpenAI-compatible?

A: It uses familiar OpenAI-style image endpoints such as /v1/images/generations, /v1/images/edits, and /v1/models.

Models

Q: Which model should I use for image generation?

A: Use nano-banana.

Q: Which model should I use for image editing?

A: Use nano-banana.

Q: Which model should I use for upscaling?

A: Use the /v1/images/upscale endpoint. The worker exposes imagen-4.0-upscale-preview for upscale support.

Q: Can I request multiple images?

A: Yes. Use n from 1 to 4 for generation and edit requests.

Inputs and Outputs

Q: Can I upload a local image file?

A: Yes. Use multipart form-data with the field name image.

Q: Can I use image URLs?

A: Yes. URLs are supported for POST and GET edit/upscale requests.

Q: Can I use base64 images?

A: Yes for POST edit and upscale requests. You can send a data URL base64 string or raw base64 string.

Q: Should I use size or aspect_ratio?

A: Prefer aspect_ratio. The size parameter exists mainly for OpenAI-compatible legacy integrations.

Q: Should I use url or b64_json?

A: Use url for simple display and downloads. Use b64_json when you want to store or process image bytes yourself.

Technical

Q: Can I use this API from a browser?

A: Yes. The API supports CORS and can be called from browser apps.

Q: Can I use GET endpoints in production?

A: You can, but POST is usually better for production because it handles longer prompts and request bodies more cleanly.

Q: What happens if generation takes too long?

A: The API may return a 504 timeout. Retry with backoff, reduce n, or simplify the request.

Q: Where can AI tools read the docs from MCP?

A: Use the remote MCP server at https://nano-banana-api.readme.io/mcp.

Copy-Paste Starter

const API_BASE = "https://nanobanana.aikit.club";

async function generateImage(prompt) {
  const response = await fetch(`${API_BASE}/v1/images/generations`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      prompt,
      model: "nano-banana",
      n: 1,
      aspect_ratio: "1:1",
      output_format: "png",
      response_format: "url"
    })
  });

  const data = await response.json();

  if (!response.ok) {
    throw new Error(data.error?.message || "Image generation failed");
  }

  return data.data[0];
}

generateImage("A cozy robot painting a banana in a sunlit studio")
  .then((image) => {
    console.log("Image URL:", image.url);
    console.log("Revised prompt:", image.revised_prompt);
  })
  .catch(console.error);