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

When an app needs both text-to-image generation and prompt-based edits, the hard part is not just calling a model once; it is designing a small workflow that can create images, revise existing assets, track results, and handle failures without surprising users.

What you can do

The Nano Banana Images API provides one HTTP endpoint for two related jobs: generating an image from a text prompt and editing one or more existing images with a prompt. Both use the same base URL, authentication style, JSON headers, and response shape, which makes it straightforward to build a single image pipeline around it.

• Generate images with action as generate and a clear prompt.
• Edit images with action as edit, a prompt, and an image_urls array.
• Request between 1 and 4 images with count; the default is 1.
• Choose an optional model, such as nano-banana, nano-banana-2-lite, nano-banana-2, nano-banana-pro, or the corresponding :official variants.
• Use callback_url when you want completion results delivered to a webhook instead of holding a long request open.

How it works

The API is exposed at https://api.acedata.cloud with the endpoint POST /nano-banana/images. Requests should include authorization: Bearer {token}, accept: application/json, and content-type: application/json. The minimum fields for generation are action and prompt. Editing adds image_urls, which must contain at least one publicly accessible image URL.

The response is designed for workflow tracking. A successful response includes success, task_id, trace_id, and a data array. Each item in data includes the echoed prompt and an image_url for a generated or edited image. Keep both task_id and trace_id in your database or logs; they are useful for associating a user action with the final image and for troubleshooting.

Generate from a prompt

A generation request is the simplest version of the workflow. The main thing to get right is the prompt: describe the subject, style, lighting, composition, and intended orientation. You can also use count when you want multiple options. The documentation notes that each image is generated by an independent call; if one attempt fails because of an ordinary technical issue or a provider security refusal, the other successful images can still return normally.

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

That request uses nano-banana-pro, but model is optional. If you omit it, the default is nano-banana. If your workflow requires a specific output shape, the API also supports optional aspect_ratio values such as 1:1 or 16:9, and optional resolution values such as 1K, 2K, or 4K. One caveat from the docs: nano-banana-2-lite only supports 1K.

Edit one or more source images

Editing uses the same endpoint, but switches action to edit and passes source materials through image_urls. The array can contain HTTP or HTTPS image URLs, and the docs also describe Base64 data URLs as supported input. In production, HTTPS direct links are usually the easiest to manage because your backend can validate and store them before calling the API.

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

A practical editing pattern is to store each source image URL with a role in your own app, such as person_photo or reference_product, then generate a concise prompt that explains the intended transformation. The API only needs image_urls and prompt, but your application will be easier to debug if you preserve the user-facing intent alongside the returned task_id.

Use callbacks for production workflows

Image generation or editing may take time, so the docs recommend a webhook callback when you do not want a long connection occupying resources. Add callback_url to the request body. The URL must be publicly accessible and support POST JSON. When the task completes, the platform sends a payload with the same structure as the synchronous success response, including success, task_id, trace_id, and data.

{
  "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, your webhook handler should verify that the task_id exists in your system, update the asset status, save the returned image_url, and keep the trace_id for support logs. If you request multiple images, remember that data only contains successfully generated images.

Handle errors deliberately

The documented error response uses success: false, an error object, and trace_id. Common error codes include invalid_token for missing or failed authentication, too_many_requests for frequency limits, forbidden when the provider security policy denies the request or result, and api_error for server exceptions. Treat trace_id as a first-class log field; it is the easiest way to connect a failed user action to a specific API attempt.

The cleanest builder experience is to wrap the API in a tiny service function: validate prompts and image URLs, send either generate or edit, persist task_id and trace_id, and update your UI from the returned or callback-delivered image_url. For the complete reference, see the Nano Banana Images API documentation.