How to Build Image Generation and Editing Workflows with the Nano Banana Images API

If your product needs both text-to-image generation and image-based editing, the hard part is usually not sending one request; it is designing a workflow that can handle prompts, reference images, callbacks, partial failures, and traceable results.

What you can do

The Nano Banana Images API exposes one image endpoint for two practical jobs: generating images from text and editing one or more existing images. The base URL is https://api.acedata.cloud, and the endpoint is POST /nano-banana/images. Authentication is done with an HTTP header: authorization: Bearer {token}.

The core switch is the action field:

• generate: create an image from a text prompt.
• edit: edit existing image material supplied through image_urls.

You can also choose a model. The default is nano-banana. Other documented options include nano-banana-2-lite, nano-banana-2, nano-banana-pro, and their corresponding :official variants. The request can ask for multiple outputs with count, from 1 to 4, with a default of 1.

How it works

Every request uses JSON and should include accept: application/json and content-type: application/json. For simple generation, only action and prompt are required. For editing, image_urls is also required and must contain at least one publicly accessible image link. HTTP and HTTPS links are supported; HTTPS is recommended. The documentation also notes that a Base64-encoded image can be used, such as a data:image/png;base64,... value.

A successful response returns success, task_id, trace_id, and a data array. Each item in data includes the echoed prompt and an image_url. Keep both task_id and trace_id: they are useful for associating requests with results and for troubleshooting.

Generate an image from a prompt

For a first integration, start with a single image. The example below uses the documented endpoint, headers, and fields. Replace {token} with your API token and keep the prompt specific enough to guide composition, subject, style, and orientation.

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
  }'

For application code, the same request maps cleanly to 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.",
    "count": 1,
}
resp = requests.post(url, json=payload, headers=headers)
print(resp.json())

Edit images with references

Editing is useful when the desired output depends on existing visual material. The API accepts multiple entries in image_urls, so you can combine a base image with another reference image and describe the edit in prompt. The documented example provides a portrait photo and a clothing photo, then asks the model to dress the person in that clothing.

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
  }'

In a real product, validate that every URL is accessible before sending the request. Broken or private image links are easy to miss during development and can make debugging feel like a model issue when it is actually an input issue.

Use callbacks for production workflows

Image generation and editing can take time. If you do not want a client or server process to hold a long connection, add callback_url to the request body. The callback URL must be publicly accessible and support JSON POST requests. The API can return quickly with a task_id, then send the final JSON payload to your callback when the task completes.

{
  "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"
    }
  ]
}

A simple pattern is to store task_id, trace_id, request parameters, and user context before returning a pending state to your own frontend. When the callback arrives, update the record with the returned image_url and notify the user interface.

Handle errors deliberately

Do not treat every failed image request the same way. The API returns structured errors with a trace_id. Documented cases include invalid_token for missing or failed authentication, too_many_requests for rate limits, api_error for server-side exceptions, and forbidden when the provider safety policy rejects the request or generated result.

One useful detail is how multi-image requests behave. Because each image is completed by an independent generation call, ordinary technical failures or provider safety rejections can affect only the corresponding call. Successful images may still be returned and billed according to the actual number of successful images. If all calls are rejected by the provider safety policy, the API returns 403.

Practical integration checklist

• Start with count: 1 until logging and callback handling are stable.
• Persist task_id and trace_id for every request.
• Use callback_url when your workflow cannot wait synchronously.
• For edits, verify that every image_urls entry is publicly accessible.
• Choose aspect_ratio and resolution only when you need them; documented examples include 1:1, 16:9, 1K, 2K, and 4K. Note that nano-banana-2-lite supports only 1K.

The result is a compact workflow: send a clear prompt, optionally attach image references, track the task, and let callbacks update your product when the image is ready. For the complete field reference and examples, read the Nano Banana Images API documentation.