# A Practical Guide to Project-Level Claude Code CLI Configuration

---
title: How to Build a Generate-and-Edit Image Workflow with the Nano Banana Images API
published: false
tags: ai, api, tutorial, machinelearning
canonical_url: https://platform.acedata.cloud/documents/nano-banana-images-integration
cover_image: https://platform2.cdn.acedata.cloud/gpt-image/b2192115-1c4e-4837-93d4-736517abee0b_0.png
---

If your product needs both text-to-image generation and practical image edits, the annoying part is usually not the prompt — it is keeping one clean API shape for both workflows.

![Cover image for Nano Banana Images API](https://platform2.cdn.acedata.cloud/gpt-image/b2192115-1c4e-4837-93d4-736517abee0b_0.png)

In this guide, we will build a small mental model for using the Nano Banana Images API through Ace Data Cloud: one endpoint, two actions, optional model selection, and a result shape that gives you image URLs plus IDs you can log for debugging.

The goal is not to wrap every feature. It is to get a builder-friendly path you can drop into a prototype: generate an image from a prompt, edit one or more public images, and decide when to use a webhook callback.

## What you can do

The Nano Banana Images API supports two main actions:

- `generate`: create images from a text `prompt`
- `edit`: transform or combine existing images using `image_urls[]` and a `prompt`

Both actions use the same base API details:

```text
Base URL: https://api.acedata.cloud
Endpoint: POST /nano-banana/images
Authentication: authorization: Bearer {token}
Headers:
  accept: application/json
  content-type: application/json
```

The minimum required request fields are `action` and `prompt`. For editing, you also pass `image_urls`, an array with at least one publicly accessible image URL. The docs note that these can be HTTP/HTTPS links, and HTTPS is recommended.

You can also choose a `model`. The default is `nano-banana`, while the guide lists `nano-banana-2-lite`, `nano-banana-2`, `nano-banana-pro`, and corresponding `:official` channel variants such as `nano-banana-pro:official`. If you do not need to tune model behavior yet, start with the default and make model selection a configuration value later.

## How it works

Think of the endpoint as a task-producing image operation. You submit JSON, receive a response with `success`, `task_id`, `trace_id`, and a `data[]` array. Each successful item in `data[]` contains the echoed `prompt` and an `image_url`.

That response shape is useful in production code because you can store:

- `task_id` as the job identifier in your own database
- `trace_id` for troubleshooting and support
- `image_url` as the artifact your app displays or downloads

Here is the smallest useful `generate` request:

```bash
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 desk lamp on a dark navy background, soft rim lighting, realistic material texture, centered composition",
    "count": 1
  }'
```

A successful response follows this pattern:

```json
{
  "success": true,
  "task_id": "70e6931b-6e34-43db-9e36-8765e2809d04",
  "trace_id": "60df8d38-f265-4986-aec7-75c9220bced2",
  "data": [
    {
      "prompt": "A clean product hero image of a compact desk lamp on a dark navy background, soft rim lighting, realistic material texture, centered composition",
      "image_url": "https://platform2.cdn.acedata.cloud/nanobanana/1d0160b4-93f9-4229-8926-ea9ef0bed336.png"
    }
  ]
}
```

The `count` field is optional and supports 1 to 4 images. The documentation also notes that if some images fail, only successful images are returned and billed, so your UI should handle a shorter `data[]` array than requested.

## Editing one or more source images

For edit workflows, the important difference is `action: "edit"` plus `image_urls[]`. The prompt should describe the transformation you want, while the image URLs provide the source material.

This makes the API fit common builder use cases:

- apply a clothing or product reference to a person image
- create consistent variants from an existing asset
- combine a base image with a second reference image
- perform lightweight creative edits without changing endpoints

Example request:

```bash
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",
    "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
  }'
```

The response has the same top-level shape as generation: `success`, `task_id`, `trace_id`, and `data[]` with an `image_url`. That symmetry is nice: your app can implement one result parser for both actions.

## Add callbacks when requests may take longer

Image operations can take time, and long HTTP connections are not always the best fit for web apps. The API supports an optional `callback_url` field. When you include it, your server provides a public webhook endpoint that can receive a POST JSON payload when the task is complete.

A practical pattern is:

1. Submit the image request with `callback_url`.
2. Save `task_id` and mark the job as pending.
3. Return immediately to the user interface.
4. When your webhook receives the completion payload, store `data[].image_url` and update the job state.

The callback payload uses the same successful response structure, including `success`, `task_id`, `trace_id`, and `data[]`, so your synchronous and asynchronous paths can share most of their parsing code.

## Handling errors without guessing

The error response includes `success: false`, an `error` object, and `trace_id`. The guide lists common error codes including `invalid_token` for authentication failure, `too_many_requests` for request frequency limits, and `api_error` for server exceptions.

A simple client should log `trace_id` on every failure and branch on `error.code` rather than trying to infer what happened from HTTP status alone.

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

## A small production checklist

Before putting this behind a user-facing button, I would add a few guardrails:

- keep `{token}` server-side and send it only in the `authorization` header
- validate that `image_urls[]` are public URLs before calling `edit`
- store `task_id` and `trace_id` for every request
- treat `data[]` as a list that may contain fewer images than `count`
- make `model`, `count`, `aspect_ratio`, and `resolution` configurable rather than hard-coded

That is enough to build a reliable first version: one endpoint for generation and editing, a predictable response format, and a callback path when you need async job handling.

If you want the exact field list and the maintained examples, the original Nano Banana Images API guide is here: https://platform.acedata.cloud/documents/nano-banana-images-integration