How to Build a Practical Image Generation and Editing Flow with the Nano Banana Images API

If you are building an app that needs both text-to-image generation and reference-based image editing, the awkward part is often not the model prompt. It is designing one API flow that handles creation, edits, retries, result tracking, and user-facing errors without special cases everywhere.

The Nano Banana Images API gives you a single endpoint for two related jobs: generating images from prompts and editing existing images with one or more references. This guide walks through a small builder-oriented integration pattern: a minimal request path, an edit path for reference images, and a callback path for production jobs.

What you can do

The documented interface supports two actions on the same endpoint:

• generate: create images from a text prompt.
• edit: edit or combine supplied images using image_urls plus a text prompt.

The base URL is https://api.acedata.cloud, and the endpoint is POST /nano-banana/images. Requests use JSON, with authorization: Bearer {token} in the header, plus accept: application/json and content-type: application/json.

The same request shape also supports optional production controls: model, count, aspect_ratio, resolution, and callback_url. The important design choice is that action decides whether you are creating from scratch or editing references.

How it works

The minimum generation request needs only action and prompt. If you do not specify a model, the default is nano-banana. The docs also list nano-banana-2-lite, nano-banana-2, nano-banana-pro, and corresponding :official variants. One useful constraint to encode in your UI is that nano-banana-2-lite only supports 1K resolution.

The response returns success, task_id, trace_id, and a data array. Each successful item contains the echoed prompt and an image_url. Keep both IDs: task_id helps associate the output with a job in your database, while trace_id is useful when troubleshooting failed calls.

Start with a minimal generation request

For a first integration, keep the server-side function boring: accept a prompt from your app, choose a model, and request a single image with count: 1. The documented count field supports 1–4 images and defaults to 1. Each image is generated by an independent call, so if one item fails because of an ordinary technical issue or provider security refusal, other successful items may still be 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 on a deep navy developer dashboard, soft studio light, realistic UI reflections",
    "count": 1
  }'

A successful response follows this shape:

{
  "success": true,
  "task_id": "70e6931b-6e34-43db-9e36-8765e2809d04",
  "trace_id": "60df8d38-f265-4986-aec7-75c9220bced2",
  "data": [
    {
      "prompt": "A clean product mockup on a deep navy developer dashboard, soft studio light, realistic UI reflections",
      "image_url": "https://platform2.cdn.acedata.cloud/nanobanana/example.png"
    }
  ]
}

Add image editing with references

Editing uses the same endpoint, but changes action to edit and adds image_urls. The documented field is an array with at least one item. URLs can be publicly accessible HTTP or HTTPS links, and the docs also describe Base64 image data such as a data:image/png;base64,... value.

This is useful for product flows where the user uploads a source image and selects a second reference image: for example, applying a design to a mockup, trying a clothing item on a person, or combining two visual inputs into a single edited result.

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 design from the second image onto the product in the first image",
    "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())

Use callbacks for production jobs

Generation and editing can take time. The API supports an optional callback_url so your backend does not need to hold a long connection open. The callback address must be publicly accessible and support POST JSON.

A practical production pattern is:

1. Create an image job in your database with status queued.
2. Call POST /nano-banana/images with your callback_url.
3. Store the returned task_id and trace_id.
4. When the callback arrives, update the job with each returned image_url.

The callback payload has the same structure as a successful response, including success, task_id, trace_id, and data.

Handle errors deliberately

The API returns a standard error object with a trace_id. The docs list common cases including 400 token_mismatched for invalid parameters, 401 invalid_token for missing or failed authentication, 403 forbidden when the provider security policy denies a request or generated result, 429 too_many_requests for frequency limits, and 500 api_error for server exceptions.

In user-facing apps, treat 403 forbidden differently from infrastructure errors. It means that particular generation did not return images and is not billed, while other successful images in a multi-image request can still return normally. For 429, stop and retry later instead of creating duplicate user jobs.

Where this fits

The cleanest integration is to model image work as jobs: one endpoint call, one stored task_id, one result list, and one error path. That keeps the same backend structure whether the user starts from a text prompt or supplies reference images for editing.

For the full parameter list and official examples, read the Nano Banana Images API documentation.