A Practical Guide to Image Generation and Editing with the Nano Banana Images API

If your app needs to generate product visuals, transform existing images, or combine multiple reference images into one result, you need an image API that is simple enough to call from a backend job but explicit enough to debug in production.

This guide walks through the Nano Banana Images API on Ace Data Cloud as a practical builder workflow: one endpoint, two actions, optional async callbacks, and response fields you can store for troubleshooting.

What you can do

The API exposes a single image endpoint, POST /nano-banana/images, under the base URL https://api.acedata.cloud. The same endpoint supports two main modes through the action field:

• generate: create images from a text prompt.
• edit: edit one or more existing images by passing image_urls plus a prompt that describes the target change.

That makes it useful for common application flows such as generating campaign mockups, creating concept art from a brief, editing a reference image, or combining a person photo with another visual asset. The important part is that the API shape stays stable across both workflows, so you can model it cleanly in your own service.

How it works

Every request is sent to:

POST https://api.acedata.cloud/nano-banana/images

The request must include these headers:

authorization: Bearer {token}
accept: application/json
content-type: application/json

For generation, the minimum required fields are action and prompt. For editing, you still provide action and prompt, but you also pass image_urls, an array with at least one image. The API accepts publicly accessible HTTP or HTTPS image URLs, and the documentation also describes support for Base64-encoded image data such as data:image/png;base64,....

You can optionally choose a model. The documented values include nano-banana, nano-banana-2-lite, nano-banana-2, nano-banana-pro, and matching :official variants. If you do not set a model, nano-banana is the default. The optional count field requests 1 to 4 images and defaults to 1.

Start with text-to-image generation

A generation request is the smallest useful integration. You send a prompt, choose the model if needed, and receive a JSON response with a task identifier and image data.

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 hero image of a compact mechanical keyboard on a dark desk, soft studio lighting, realistic materials, high detail.",
    "count": 1
  }'

A successful response includes success, task_id, trace_id, and a data array. Each item in data contains the echoed prompt and an image_url. In practice, save both task_id and trace_id with your internal job record. If a user reports a bad output or a failed request, those fields are the easiest way to connect your logs with the platform response.

Edit existing images with image_urls

Editing uses the same endpoint but changes the payload. Set action to edit, describe the intended transformation in prompt, and pass the source materials in image_urls.

{
  "action": "edit",
  "prompt": "Place the product from the first image into the lifestyle scene from the second image while keeping realistic lighting.",
  "image_urls": [
    "https://cdn.acedata.cloud/v8073y.png",
    "https://cdn.acedata.cloud/44xlah.png"
  ],
  "count": 1
}

This pattern is especially useful when your application already stores user-provided assets. For example, a commerce tool could let a seller upload a plain product photo and then generate lifestyle variations by combining it with different room or desk references. The API documentation notes that multiple images can be provided, and the service combines the materials with the prompt to complete the edit.

Use callback_url for longer jobs

Image generation and editing can take time. If you do not want a client or worker process to hold a long connection open, add callback_url to the JSON body. The callback URL must be publicly accessible and support POST JSON.

{
  "action": "generate",
  "prompt": "A minimal dashboard illustration showing an image workflow pipeline.",
  "callback_url": "https://example.com/webhooks/nano-banana",
  "count": 1
}

With this approach, your app can create an internal job, send the API request, and then mark the job complete when the webhook arrives. The callback payload uses the same structure as a synchronous successful response, including success, task_id, trace_id, and data with image_url.

Handle partial success and errors deliberately

The count field can request multiple images. The documentation says each image is generated by an independent call, and ordinary technical failures or provider security refusals only affect the corresponding call. Successful images can still return in data, and billing is based on the actual number of successful images returned.

For error handling, expect a standard JSON error shape with success: false, an error object, and trace_id. Documented error codes include invalid_token for missing or failed authentication, too_many_requests for request frequency limits, forbidden when the provider security policy denies the request or generated result, and api_error for server exceptions.

A small production rule of thumb: store the original request body, task_id, trace_id, and returned image_url together. That gives you enough context to retry safely, show useful support messages, and separate prompt problems from infrastructure issues.

Where to go next

If you are building an image feature, start with one narrow workflow: text-to-image generation for a known prompt template, or image editing with one or two reference images. Once that works, add callback_url and job tracking so the user experience stays responsive even when rendering takes longer.

Read the full API reference in the Nano Banana Images API Integration Guide.