Nano Banana Images API Integration Instructions

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

Application Process

To use the Nano Banana Images API, first obtain your API Token from the Ace Data Cloud Console for future reference.

If you are not logged in or registered, you will be automatically redirected to the login page to invite you to register and log in, and after completion, you will be automatically returned to the current page. One API Token can call all services on the platform without needing to apply separately for each service. The first application will grant a free quota for a trial experience; when the quota is insufficient, you can recharge the general balance in the console.

📘 Complete Documentation: Nano Banana Images API →

Interface Overview

Base URL: https://api.acedata.cloud
Endpoint: POST /nano-banana/images
Authentication Method: Include authorization: Bearer {token} in the HTTP Header
Request Headers:
- accept: application/json
- content-type: application/json
Actions:
- generate: Generate images based on text prompts
- edit: Edit based on given images
Models (optional):
- nano-banana (default): Based on Gemini 2.5 Flash Image, fast speed, low cost
- nano-banana-2-lite: Based on Gemini 3.1 Flash Lite Image, supports only 1K, fast generation speed
- nano-banana-2: Based on Gemini 3.1 Flash Image Preview, Pro-level quality + Flash speed
- 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, better image quality and stability, different billing
Asynchronous Callback: Optional, receive task completion notifications and results via callback_url
Number of Images: Optional, specify 1–4 images via count, default is 1; if some fail, only successful images will be returned and billed

Quick Start: Generate Image (`action=generate`)

Minimum Required Parameters: action, prompt When you only want to generate an image 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://platform2.cdn.acedata.cloud/nanobanana/1d0160b4-93f9-4229-8926-ea9ef0bed336.png"
    }
  ]
}

Field Explanation

success: Whether the request was successful.
task_id: Task ID.
trace_id: Link tracking ID, useful for troubleshooting.
count: The number of images requested for generation or editing, supports 1–4, default is 1. If some fail, data only contains successful images.
data[]: Result list.
- prompt: The prompt used for generation (echo).
- image_url: Direct URL of the generated image.

Note: Only action and prompt are required to generate an image at /nano-banana/images

Edit Image (`action=edit`)

When you want to edit based on an existing image, set action to edit, and pass the list of image URLs to be edited through image_urls (1 or more), while also providing a prompt describing the editing goal. For example, if we provide a photo of a person and a photo of a shirt, we can have the person wear that shirt by passing the image URLs and specifying the action as edit. The URLs can be HTTP URLs, publicly accessible links using https or http protocols, or Base64 encoded images, 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())

Example of Successful Return

{
  "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 sent, and the service will combine these materials with the prompt to complete the editing.
Other fields are the same as the “Generate Image” return.

Asynchronous Callback (Optional, Recommended)

Generation or editing may take some time. To avoid long connections occupying resources, it is recommended to use Webhook Callback via callback_url:

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

Callback Payload Example (Field structure is consistent with synchronous successful return):

{
  "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 the 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 parameters are incorrect.
400 api_not_implemented: The interface is not implemented (please contact support).
401 invalid_token: Authentication failed or token is missing.
429 too_many_requests: Request frequency limit exceeded.
500 api_error: Server exception.

Error Response Example

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

Parameter Correspondence and Notes

Required: action, prompt
Editing Specific: image_urls (array, at least 1 item)
Optional: model (default nano-banana, optional nano-banana-2-lite, nano-banana-2, nano-banana-pro, or corresponding :official official channel version), aspect_ratio (width-to-height ratio, such as 1:1, 16:9), resolution (resolution, such as 1K, 2K, 4K; nano-banana-2-lite only supports 1K), callback_url (for asynchronous callback)
Headers: Must provide authorization: Bearer {token}; accept is recommended to be set to application/json
Image Accessibility: image_urls must be direct links that are publicly accessible (HTTP/HTTPS), HTTPS is recommended
Idempotency and Tracking: Retain task_id and trace_id for troubleshooting and result association.

Getting Started

Core Concepts

AI Chat

AI Image

AI Video

AI Audio

Web & Data

CAPTCHA

Identity

Proxy

Advanced

Nano Banana Images API Integration Instructions

Application Process

Interface Overview

Quick Start: Generate Image (`action=generate`)

Request Example (cURL)

Request Example (Python)

Successful Response Example

Field Explanation

Edit Image (`action=edit`)

Request Example (cURL)

Request Example (Python)

Example of Successful Return

Field Description

Asynchronous Callback (Optional, Recommended)

Error Handling

Error Response Example

Parameter Correspondence and Notes

​Application Process

​Interface Overview

​Quick Start: Generate Image (action=generate)

​Request Example (cURL)

​Request Example (Python)

​Successful Response Example

​Field Explanation

​Edit Image (action=edit)

​Request Example (cURL)

​Request Example (Python)

​Example of Successful Return

​Field Description

​Asynchronous Callback (Optional, Recommended)

​Error Handling

​Error Response Example

​Parameter Correspondence and Notes

Application Process

Interface Overview

Quick Start: Generate Image (`action=generate`)

Request Example (cURL)

Request Example (Python)

Successful Response Example

Field Explanation

Edit Image (`action=edit`)

Request Example (cURL)

Request Example (Python)

Example of Successful Return

Field Description

Asynchronous Callback (Optional, Recommended)

Error Handling

Error Response Example

Parameter Correspondence and Notes