A Practical Guide to Image Generation and Editing with the Nano Banana Images API

If your product workflow needs to create images from prompts and also edit existing assets, the hard part is usually not the model itself — it is building a predictable API flow around prompts, source images, callbacks, and result tracking.

This guide walks through the Nano Banana Images API on Ace Data Cloud as a practical image generation and editing endpoint. We will focus on the parts a builder actually needs: the endpoint, required fields, generation vs. editing, callbacks, and how to keep enough IDs around to debug failed or delayed jobs.

What you can do

The Nano Banana Images API exposes one HTTP endpoint for two related actions:

generate: create images from a text prompt.
edit: edit or combine one or more existing images using image_urls plus a text prompt.

The API is useful when you want one integration path for common product image tasks: generating a blog illustration, creating a product concept, adapting a reference image, or combining a person image with another visual asset. The request can return generated image URLs directly, and it can also use a webhook via callback_url when you do not want to keep a connection open while the task runs.

How it works

The base URL is https://api.acedata.cloud, and the image endpoint is:

POST /nano-banana/images

Requests are JSON. The required headers are straightforward:

authorization: Bearer {token}
accept: application/json
content-type: application/json

For a minimum generation request, only action and prompt are required. For editing, you still provide action and prompt, but you also pass image_urls, an array with at least one publicly accessible image URL. The API supports HTTP/HTTPS URLs, and HTTPS direct links are recommended. The same field can also contain Base64 encoded image data such as a data:image/png;base64,... string.

Choosing the right action

Use action: "generate" when the image can be described fully in text. This is the simplest path for editorial visuals, mock scenes, illustration drafts, or creative variants.

Use action: "edit" when the output must be grounded in one or more source images. A typical example is passing a person image and a clothing image, then asking the model to make the person wear that shirt. In this mode, image_urls gives the model the source material, while prompt describes the transformation.

The endpoint also accepts optional model choices, including nano-banana, nano-banana-2-lite, nano-banana-2, nano-banana-pro, and the corresponding :official channel versions. If you do not set model, the default is nano-banana.

Controlling output size and count

The optional count field controls how many images you request. The documented range is 1–4, and the default is 1. If some images fail while others succeed, the response returns only the successful items in data.

You can also use aspect_ratio, such as 1:1 or 16:9, and resolution, such as 1K, 2K, or 4K. One important constraint from the documentation: nano-banana-2-lite supports only 1K.

A minimal generation request

Here is a compact cURL request you can adapt. Replace {token} with your API token and rewrite the prompt for your own use case.

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 clean developer workspace showing an API workflow for image generation, with a terminal, an image preview panel, and soft blue lighting.",
    "count": 1
  }'

A successful response includes success, task_id, trace_id, and a data array. Each result item includes the echoed prompt and an image_url pointing to the generated image.

{
  "success": true,
  "task_id": "70e6931b-6e34-43db-9e36-8765e2809d04",
  "trace_id": "60df8d38-f265-4986-aec7-75c9220bced2",
  "data": [
    {
      "prompt": "A clean developer workspace showing an API workflow for image generation, with a terminal, an image preview panel, and soft blue lighting.",
      "image_url": "https://platform2.cdn.acedata.cloud/nanobanana/example.png"
    }
  ]
}

Editing with source images

For editing, the shape is almost the same, but image_urls becomes the key field. The URLs must be direct and publicly accessible so the service can fetch the source images.

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())

For production code, keep both task_id and trace_id. The task_id helps you associate a request with its output, while trace_id is useful when troubleshooting errors or support cases.

Using callbacks for longer jobs

Image generation and editing may take time. If you do not want your client to wait on the request, include callback_url in the body. The URL must be publicly accessible and able to receive a POST JSON payload. When the task completes, the platform sends a payload with the same structure as a successful response: success, task_id, trace_id, and data containing the final image_url.

That pattern is especially useful in web apps: submit the task, store task_id, show a pending state, and update the asset when your webhook receives the final result.

Error handling basics

The API returns a standard error shape with success: false, an error object, and trace_id. Common documented error codes include token_mismatched, api_not_implemented, invalid_token, too_many_requests, and api_error.

In practice, treat 401 invalid_token as an authentication issue, 429 too_many_requests as a signal to slow down, and keep the returned trace_id in your logs. That small logging habit saves time when a user reports that an image did not appear.

Wrapping up

The nice part of this API is that generation and editing share the same endpoint and response pattern. Start with action, prompt, and count; add image_urls when you need editing; add callback_url when the workflow should run asynchronously. That is enough to build a clean first version without over-engineering the image pipeline.

Read the full API reference here: Nano Banana Images API Integration Guide.

Search This Blog

AceDataCloud