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

Most image features start as a simple prompt box, but the moment you put them into a real product you need a repeatable API contract: authentication, input images, task tracking, and predictable error handling.

What you can do

The Nano Banana Images API exposes one endpoint for two closely related jobs: generating images from text and editing existing images. The base URL is https://api.acedata.cloud, and the endpoint is POST /nano-banana/images. Authentication is handled with an HTTP header: authorization: Bearer {token}. Requests should send accept: application/json and content-type: application/json.

The API is useful when you want to add image creation to a web app, build a small internal content tool, or run a lightweight creative workflow from a script. Instead of building separate paths for text-to-image and image-to-image work, you switch behavior with the action field:

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

The same response shape gives you success, task_id, trace_id, and a data array containing returned images.

How it works

At minimum, a generation request needs action and prompt. Editing also needs image_urls, an array with at least one publicly accessible image URL. The documentation notes that HTTP and HTTPS image URLs are supported, and Base64 data URLs can also be used. In practice, HTTPS direct links are the simplest choice for production because the service can fetch the source assets without needing your private session.

You can optionally choose a model. The documented options include nano-banana as the default, nano-banana-2-lite, nano-banana-2, nano-banana-pro, and matching official-channel variants such as nano-banana-pro:official. The docs also describe optional aspect_ratio, resolution, and callback_url. One important constraint: nano-banana-2-lite supports only 1K resolution.

Generating an image from a prompt

Use action: generate when the user provides a textual description and no source image. A good prompt should define the subject, style, composition, lighting, and output orientation. The count field lets you request 1–4 images, with a default of 1. The documentation states that each image is generated by an independent call, so ordinary technical failures or provider safety refusals affect only the corresponding item. The data array contains successfully generated images and billing follows the actual number returned.

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 product mockup of a compact desk lamp on a minimal oak desk, soft morning light, realistic shadows, 16:9 composition",
    "count": 1
  }'

A successful response includes the generated image URL inside data[]:

{
  "success": true,
  "task_id": "70e6931b-6e34-43db-9e36-8765e2809d04",
  "trace_id": "60df8d38-f265-4986-aec7-75c9220bced2",
  "data": [
    {
      "prompt": "A clean product mockup of a compact desk lamp on a minimal oak desk, soft morning light, realistic shadows, 16:9 composition",
      "image_url": "https://platform2.cdn.acedata.cloud/nanobanana/1d0160b4-93f9-4229-8926-ea9ef0bed336.png"
    }
  ]
}

Editing one or more source images

Use action: edit when your workflow starts with existing assets. This is the right mode for product previews, visual variations, outfit or object transfer, background adjustments, and multi-image composition. The request includes image_urls and a natural-language instruction in prompt. The API combines the provided material with the instruction and returns edited results in the same data[] format.

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": "Place the product from the first image into the workspace scene from the second image, keeping realistic lighting and shadows.",
    "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 a production application, validate image URLs before sending the request. Check that the URL is public, fetchable, and points to the expected file. Keep the returned task_id and trace_id in your logs so support and debugging can connect a user action to an API result.

Using callbacks for longer-running jobs

Image generation and editing may take time. If you do not want clients holding an open connection, include callback_url. The callback URL must be publicly accessible and support POST JSON. The API can return a task_id immediately, then send the complete result payload to your webhook when the task finishes.

{
  "action": "generate",
  "prompt": "A white siamese cat",
  "callback_url": "https://example.com/webhooks/nano-banana",
  "count": 1
}

Your webhook should treat the callback body like the normal success response: read success, store task_id and trace_id, then iterate through data[] for each image_url.

Handling errors without confusing users

The documented error response uses success: false, an error object, and trace_id. Common cases include invalid_token for missing or failed authentication, too_many_requests for rate limiting, api_error for server exceptions, and forbidden when the provider's native safety policy denies the request or generated result. If you request multiple images, a refusal for one item may still allow other successful items to return.

A practical UI pattern is to show the successfully returned images first, then display a small retry or adjustment message for failed items. In logs, store the exact trace_id. In your retry logic, avoid blindly resubmitting the same unsafe prompt; ask the user to revise it instead.

Putting it together

The cleanest first integration is a small server endpoint that accepts a user prompt, chooses generate or edit, forwards the request to POST /nano-banana/images, and saves task_id, trace_id, and returned image_url values. That gives you enough structure for galleries, audit logs, retries, and asynchronous delivery without introducing a large media pipeline.

For the full parameter reference and the original examples, read the Nano Banana Images API documentation.

Search This Blog

AceDataCloud