Nano Banana Images API Integration Guide

This document introduces the integration and usage of the Nano Banana Images API. This API supports two capabilities: image generation (generate) and image editing (edit).

Application Process

To use the Nano Banana Images API, first go to the Ace Data Cloud Console to obtain your API Token and keep it for later use.

If you have not logged in or registered yet, you will be automatically redirected to the login page to register and log in, and will automatically return to the current page after completion.

One API Token can call all platform services; there is no need to apply separately for each service. Your first application will receive free credits for a free trial; when credits are insufficient, you can recharge your general balance in the Console.

📘 Full documentation: Nano Banana Images API →

API Overview

  • Base URL: https://api.acedata.cloud
  • Endpoint: POST /nano-banana/images
  • Authentication: Include authorization: Bearer {token} in the HTTP Header
  • Request Headers:
    • accept: application/json
    • content-type: application/json
  • Actions (action):
    • generate: Generate images based on text prompts
    • edit: Edit based on given images
  • Models (model) (optional):
    • nano-banana (default): Based on Gemini 2.5 Flash Image, fast and low cost
    • nano-banana-2-lite: Based on Gemini 3.1 Flash Lite Image, supports 1K only, fast generation speed
    • nano-banana-2: Based on Gemini 3.1 Flash Image Preview, Pro-level quality + Flash speed
    • nano-banana-2.1: A new-generation efficient image model supporting 1K, 2K, and 4K image generation and editing
    • nano-banana-pro: Based on Gemini 3 Pro Image Preview, highest quality
    • nano-banana:official, nano-banana-2-lite:official, nano-banana-2:official, nano-banana-pro:official: Official-channel versions of the corresponding models, with better image quality and stability, and different billing
  • Asynchronous Callback: Optional; receive task completion notifications and results through callback_url
  • Image Count: Optional; specify 1–4 images through count, with a default of 1; each image is completed by an independent generation call; ordinary technical failures or provider safety rejections only affect the corresponding call, while other successfully generated images are returned as usual and billed according to the actual number of successful images

Quick Start: Generate Images (action=generate)

Minimum required parameters: action, prompt
When you only want to generate an image directly based on a prompt, set action to generate and provide a clear prompt.

Request Example (cURL)

curl -X POST 'https://api.acedata.cloud/nano-banana/images' \
  -H 'authorization: Bearer {token}' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -d '{
    "action": "generate",
    "model": "nano-banana-pro",
    "prompt": "A photorealistic close-up portrait of an elderly Japanese ceramicist with deep, sun-etched wrinkles and a warm, knowing smile. He is carefully inspecting a freshly glazed tea bowl. The setting is his rustic, sun-drenched workshop. The scene is illuminated by soft, golden hour light streaming through a window, highlighting the fine texture of the clay. Captured with an 85mm portrait lens, resulting in a soft, blurred background (bokeh). The overall mood is serene and masterful. Vertical portrait orientation.",
    "count": 1
  }'

Request Example (Python)

import requests

url = "https://api.acedata.cloud/nano-banana/images"
headers = {
    "authorization": "Bearer {token}",
    "accept": "application/json",
    "content-type": "application/json",
}
payload = {
    "action": "generate",
    "model": "nano-banana-pro",
    "prompt": (
        "A photorealistic close-up portrait of an elderly Japanese ceramicist "
        "with deep, sun-etched wrinkles and a warm, knowing smile. He is carefully "
        "inspecting a freshly glazed tea bowl. The setting is his rustic, sun-drenched "
        "workshop. The scene is illuminated by soft, golden hour light streaming through "
        "a window, highlighting the fine texture of the clay. Captured with an 85mm "
        "portrait lens, resulting in a soft, blurred background (bokeh). The overall mood "
        "is serene and masterful. Vertical portrait orientation."
    ),
    "count": 1
}
resp = requests.post(url, json=payload, headers=headers)
print(resp.json())

Successful Response Example

{
  "success": true,
  "task_id": "70e6931b-6e34-43db-9e36-8765e2809d04",
  "trace_id": "60df8d38-f265-4986-aec7-75c9220bced2",
  "data": [
    {
      "prompt": "A photorealistic close-up portrait of an elderly Japanese ceramicist with deep, sun-etched wrinkles and a warm, knowing smile. He is carefully inspecting a freshly glazed tea bowl. The setting is his rustic, sun-drenched workshop. The scene is illuminated by soft, golden hour light streaming through a window, highlighting the fine texture of the clay. Captured with an 85mm portrait lens, resulting in a soft, blurred background (bokeh). The overall mood is serene and masterful. Vertical portrait orientation.",
      "image_url": "https://cdn.acedata.cloud/assets/examples/nanobanana/1d0160b4-93f9-4229-8926-ea9ef0bed336-34b3dc2195e8.png"
    }
  ]
}

Field Descriptions

  • success: Whether this request was successful.
  • task_id: Task ID.
  • trace_id: Trace ID for troubleshooting.
  • count: The number of images requested for generation or editing, supporting 1–4, with a default of 1. data contains only successfully generated images and is billed according to the actual number of returned images. Each generation call is required to use the provider's native safety policy; a rejected call does not affect other successful calls, and a 403 is returned when all calls are rejected.
  • data[]: Result list.
    • prompt: The prompt used for generation (echoed).
    • image_url: Direct URL of the generated image.

Note: /nano-banana/images only requires action and prompt to generate images

Edit Images (action=edit)

When you want to edit based on existing images, set action to edit, pass in a list of image links to be edited (one or multiple images) through image_urls, and provide a prompt describing the editing target.

For example, here we provide a photo of a person and a photo of clothing, and want the person to wear this clothing. You can pass in the image links at the same time and specify action as edit. The URL can be an HTTP URL, a publicly accessible link using the https or http protocol, or a Base64-encoded image, such as data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA+gAAAVGCAMAAAA6u2FyAAADAFBMVEXq6uwdHCEeHyMdHS....

Request Example (cURL)

curl -X POST 'https://api.acedata.cloud/nano-banana/images' \
  -H 'authorization: Bearer {token}' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -d '{
    "action": "edit",
    "prompt": "let this man wear on this T-shirt",
    "image_urls": [
      "https://cdn.acedata.cloud/v8073y.png",
      "https://cdn.acedata.cloud/44xlah.png"
    ],
    "count": 1
  }'

Request Example (Python)

import requests

url = "https://api.acedata.cloud/nano-banana/images"
headers = {
    "authorization": "Bearer {token}",
    "accept": "application/json",
    "content-type": "application/json",
}
payload = {
    "action": "edit",
    "prompt": "let this man wear on this T-shirt",
    "image_urls": [
        "https://cdn.acedata.cloud/v8073y.png",
        "https://cdn.acedata.cloud/44xlah.png"
    ],
    "count": 1
}
resp = requests.post(url, json=payload, headers=headers)
print(resp.json())

Successful Response Example

{
  "success": true,
  "task_id": "93f11baf-347b-4bb4-9520-8653cb46d6a3",
  "trace_id": "a9063166-26ed-4451-85b5-54e896817c69",
  "data": [
    {
      "prompt": "let this man wear on this T-shirt",
      "image_url": "https://platform.cdn.acedata.cloud/nanobanana/8e9e0253-26f4-45b9-b3f8-ac1aed1c284b.png"
    }
  ]
}

Field Description

  • image_urls[]: List of image URLs to be edited (must be publicly accessible). Multiple images can be provided; the service will combine these materials with the prompt to complete the editing.
  • Other fields are the same as the response for "Generate Image".

Asynchronous Callback (Optional, Recommended)

Generating or editing may take some time. To avoid long connections consuming resources, it is recommended to use a Webhook callback through callback_url:

  1. Add callback_url to the request body, for example, your server-side Webhook address (must be publicly accessible and support POST JSON).
  2. The API will immediately return a response containing task_id (or containing basic results).
  3. When the task is complete, the platform will send the full JSON to callback_url via POST. You can associate the request with the result through task_id.

Callback Payload Example (the field structure is consistent with the synchronous successful response):

{
  "success": true,
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c",
  "trace_id": "9b4b1ff3-90f2-470f-b082-1061ec2948cc",
  "data": [
    {
      "prompt": "a white siamese cat",
      "image_url": "https://platform.cdn.acedata.cloud/nanobanana/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.png"
    }
  ]
}

Error Handling

When a call fails, a standard error format and trace ID will be returned. Common errors are as follows:

  • 400 token_mismatched: The request is invalid or there is a parameter error.
  • 400 api_not_implemented: The API is not implemented (please contact support).
  • 401 invalid_token: Authentication failed or Token is missing.
  • 403 forbidden: The provider's native security policy rejected the request or generated result. This call will not return an image and will not be charged; multi-image requests may still return and charge for other successful calls.
  • 429 too_many_requests: Request rate limit exceeded.
  • 500 api_error: Server-side exception.

Error Response Example

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "Internal server error."
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Parameter Reference and Notes

  • Required: action, prompt
  • Edit-only: image_urls (array, at least 1 item)
  • Optional: model (default: nano-banana; optional: nano-banana-2-lite, nano-banana-2, nano-banana-2.1, nano-banana-pro; except for nano-banana-2.1, corresponding :official official-channel versions are also available), aspect_ratio (aspect ratio, such as 1:1, 16:9), resolution (resolution, such as 1K, 2K, 4K; nano-banana-2-lite supports only 1K), callback_url (used for asynchronous callbacks)
  • Headers: authorization: Bearer {token} must be provided; accept is recommended to be set to application/json
  • Image Accessibility: image_urls must be publicly accessible direct links (HTTP/HTTPS); HTTPS is recommended
  • Idempotency and Tracking: Retain task_id and trace_id for troubleshooting and result association