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

Image workflows often start simple: generate a mockup, edit an existing asset, and hand the final URL to the next part of your app. The part that gets messy is turning that into a reliable API flow with authentication, traceable jobs, webhooks, and predictable request shapes.

What you can do

The Nano Banana Images API exposes one endpoint, POST /nano-banana/images, on the base URL https://api.acedata.cloud. It supports two practical actions:

generate: create an image from a text prompt.
edit: modify or combine one or more existing images with image_urls and a prompt.

That covers a useful range of builder tasks: product hero images, social post variations, visual placeholders for prototypes, background replacement, style transfer across assets, or multi-image edits such as applying a clothing reference to a person photo.

How it works

Every request is a JSON POST to https://api.acedata.cloud/nano-banana/images. Authentication is passed in the HTTP header as authorization: Bearer {token}. The docs also recommend accept: application/json and content-type: application/json.

The minimum request for generation is just action and prompt. For editing, add image_urls, an array containing at least one image. The API accepts public HTTP or HTTPS image links, and it also supports Base64 data URLs such as data:image/png;base64,.... HTTPS is recommended when you use remote files.

The optional model field lets you choose among nano-banana, nano-banana-2-lite, nano-banana-2, nano-banana-pro, or the matching :official variants. If you omit it, the default is nano-banana. You can also use aspect_ratio, such as 1:1 or 16:9, and resolution, such as 1K, 2K, or 4K. One important constraint: nano-banana-2-lite only supports 1K.

Start with a generation request

For many apps, the first integration is a single generated image. The response contains success, task_id, trace_id, and a data array. Each item in data includes the echoed prompt and an image_url you can store or render in your UI.

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-2",
    "prompt": "A clean product hero image for a desk lamp on a minimal workstation, soft natural light, realistic shadows, 16:9 composition.",
    "count": 1,
    "aspect_ratio": "16:9",
    "resolution": "1K",
}
resp = requests.post(url, json=payload, headers=headers)
print(resp.json())

The documented success shape looks like this:

{
  "success": true,
  "task_id": "70e6931b-6e34-43db-9e36-8765e2809d04",
  "trace_id": "60df8d38-f265-4986-aec7-75c9220bced2",
  "data": [
    {
      "prompt": "A clean product hero image...",
      "image_url": "https://platform2.cdn.acedata.cloud/nanobanana/1d0160b4-93f9-4229-8926-ea9ef0bed336.png"
    }
  ]
}

Keep both task_id and trace_id. The former identifies the image task; the latter is useful when troubleshooting or matching logs across your own system and the platform response.

Edit existing images with `image_urls`

Editing uses the same endpoint. Change action to edit, provide a natural-language editing goal in prompt, and pass the source assets through image_urls. Multiple images can be sent, and the service combines those materials with the prompt to complete the edit.

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",
    "model": "nano-banana-pro",
    "prompt": "Replace the plain product photo background with a clean desk scene, keep the object shape unchanged, and preserve realistic lighting.",
    "image_urls": [
      "https://example.com/product-photo.png"
    ],
    "count": 1,
    "aspect_ratio": "16:9",
    "resolution": "2K",
    "callback_url": "https://example.com/webhooks/nano-banana"
  }'

Use direct, publicly accessible image URLs. If your source files live behind authentication, upload them somewhere your backend can expose safely for the request, or send a supported Base64 data URL. For production systems, I usually validate that each URL is reachable before calling the image endpoint; it makes failures easier to explain to users.

Request multiple images carefully

The optional count field supports 1 to 4 images and defaults to 1. The docs describe each requested image as an independent call. That matters for reliability: ordinary technical failures or provider security refusals can affect one image without necessarily failing the others. The data array contains successfully generated images.

If a provider security policy denies a request, the API may return 403 forbidden. In a multi-image request, other successful calls may still return normally. If all calls are rejected, no images are returned.

Use callbacks for longer-running work

Image generation and editing may take time. The API supports an optional callback_url field for asynchronous completion. Your callback endpoint must be publicly accessible and able to receive POST JSON. The platform can immediately return a response containing the task_id, then post the completed payload later.

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

In a real app, store a row before you call the API, keyed by your internal job ID and the returned task_id. When the webhook arrives, update that row with data[].image_url and surface the result to the user. This is usually cleaner than holding an HTTP connection open from a web request.

Handle errors as first-class responses

Failures use a standard shape with success: false, an error object, and trace_id. The documented error codes include token_mismatched, api_not_implemented, invalid_token, forbidden, too_many_requests, and api_error.

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

For builders, the simplest production rule is: log trace_id, show a user-safe message, and retry only when the code indicates a temporary condition. Do not blindly retry forbidden results; the provider’s native security policy may be the reason the image was not returned.

Putting it together

A good first implementation is small: one form field for prompt, an optional list of source images for edit mode, count: 1, and a webhook receiver for completion. Once that works, add model selection, aspect_ratio, and resolution as deliberate product choices rather than exposing every knob at once.

If you want the exact request fields and examples, read the Nano Banana Images API integration guide.

Search This Blog

AceDataCloud