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

If your product needs both prompt-based image generation and edits based on existing assets, the awkward part is usually not the prompt itself—it is designing a workflow that handles source images, async results, partial failures, and traceability without turning your backend into a pile of one-off scripts.

What you can do

The Nano Banana Images API exposes a single image endpoint for two related jobs: generating images from text and editing images from one or more input images. The base URL is https://api.acedata.cloud, and the endpoint is POST /nano-banana/images.

The request is JSON over HTTP. You authenticate with authorization: Bearer {token} and normally send accept: application/json plus content-type: application/json. The two core modes are controlled by the action field:

• generate: create images from a text prompt.
• edit: edit or combine existing images using image_urls and a prompt.

For builders, that means you can keep one integration surface while supporting several product features: prompt-to-image creation, product mockups, visual variations, asset composition, or guided edits based on uploaded references.

How it works

The minimum generation request needs only action and prompt. Editing also needs image_urls, an array with at least one source image. Those URLs can be public HTTP or HTTPS links, and the documentation also shows Base64 data URLs as a supported input form.

The API returns a JSON response with success, task_id, trace_id, and a data array. Each item in data includes the echoed prompt and an image_url. Keep both task_id and trace_id; they are useful for correlating a UI request with the result and for troubleshooting failed runs.

You can request multiple images with count, from 1 to 4, with a default of 1. Each image is generated by an independent call. The useful operational detail is that normal technical failures or provider security refusals affect only the corresponding image call; successful images can still be returned in the same request.

Choosing a model

The optional model field defaults to nano-banana. The documented choices include nano-banana, nano-banana-2-lite, nano-banana-2, and nano-banana-pro, along with corresponding :official variants. The docs describe nano-banana-2-lite as supporting only 1K, so do not ask it for higher resolutions in production code.

Other optional parameters include aspect_ratio, such as 1:1 or 16:9, and resolution, such as 1K, 2K, or 4K. Treat these as product-level controls: a social preview tool might default to 16:9, while a profile image flow might use 1:1.

Generate an image with cURL

Here is a compact generation request you can adapt for a backend job or an internal tool:

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 studio product photo of a matte black mechanical keyboard on a dark desk, soft side lighting, realistic shadows, minimal background",
    "aspect_ratio": "16:9",
    "resolution": "1K",
    "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 studio product photo...",
      "image_url": "https://platform2.cdn.acedata.cloud/nanobanana/example.png"
    }
  ]
}

Edit images with references

Editing is the mode to use when the prompt alone is not enough. For example, you can provide a product image and a background image, then ask the model to place the product into that scene. The important field is image_urls.

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 naturally on the desk, keep the logo visible, preserve realistic lighting",
    "image_urls": [
        "https://cdn.example.com/product.png",
        "https://cdn.example.com/desk-scene.png"
    ],
    "count": 1
}

resp = requests.post(url, json=payload, headers=headers)
print(resp.json())

In a real application, validate that each source image is publicly reachable before calling the API. If you accept user uploads, upload them to a storage location that produces direct HTTP or HTTPS URLs, then pass those URLs in image_urls.

Use callbacks for production workflows

Image jobs may take time, so the API supports an optional callback_url. Add it to the request body when you want the platform to POST the completed JSON result back to your server. The callback payload uses the same successful response structure, including success, task_id, trace_id, and data.

A practical pattern is: create a database row with a local job ID, call the API, store task_id and trace_id, return immediately to the user, then update the row when your webhook receives the callback. That keeps the UI responsive and gives support staff enough IDs to debug failed or delayed requests.

Handle errors explicitly

The documented error format includes success: false, an error object with code and message, and a trace_id. Common codes include invalid_token for missing or failed authentication, too_many_requests for frequency limits, forbidden for provider security-policy denials, and api_error for server exceptions.

Do not collapse all failures into a generic “generation failed” message. Surface a useful user-facing explanation, keep the trace_id in logs, and avoid retrying blindly on policy refusals.

Wrapping up

The main advantage of this API design is that generation, editing, model selection, multi-image counts, callbacks, and trace IDs all fit into one endpoint. That is enough structure to build a reliable image workflow without overengineering the first version.

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