How to Generate and Edit Images with the Nano Banana Images API

How to Generate and Edit Images with the Nano Banana Images API

Image generation integrations can become difficult when an API must support both prompt-based generation, image editing, asynchronous delivery, and partial failures across multiple requested images.

What you can do

The Nano Banana Images API is available from the Ace Data Cloud API base URL:

https://api.acedata.cloud

Use the following endpoint to generate new images or edit existing ones:

POST /nano-banana/images

The API accepts two actions:

  • generate creates images from a prompt.
  • edit modifies one or more supplied source images using a prompt.

Every request requires action and prompt. Editing requests additionally require image_urls, an array containing at least one image. Each image URL can be a publicly accessible direct HTTP or HTTPS link, or a Base64 data image.

An application token is obtained from the Ace Data Cloud Console. One API token can call platform services. Send that token in the authorization header as a Bearer token.

How it works

Send a JSON request to https://api.acedata.cloud/nano-banana/images with the required headers:

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

The optional model field defaults to nano-banana. Available model values are nano-banana, nano-banana-2-lite, nano-banana-2, and nano-banana-pro, plus their corresponding :official versions. The nano-banana-2-lite model supports 1K resolution only.

You can also send count from 1 through 4, with a default of 1. Use aspect_ratio for values such as 1:1 or 16:9, and resolution for values such as 1K, 2K, or 4K.

A successful response includes success, task_id, trace_id, and a data array. Each data item includes the prompt and an image_url.

Generate images from a prompt

This curl request generates one image with the default model. The request explicitly sets a square aspect ratio and 1K resolution.

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",
    "prompt": "A detailed illustration of a mountain landscape at sunrise",
    "count": 1,
    "aspect_ratio": "1:1",
    "resolution": "1K"
  }'

If you need multiple outputs, set count to a value from 1 to 4. Each requested image is an independent generation call. This matters when a provider safety policy rejects one image: other requested images can still succeed, and billing is based on actual successful images.

A success payload has this structure:

{
  "success": true,
  "task_id": "...",
  "trace_id": "...",
  "data": [{"prompt": "A detailed illustration of a mountain landscape at sunrise", "image_url": "..."}]
}

Edit an existing image

For edit, include image_urls with at least one source image. The URLs must be publicly accessible direct HTTP or HTTPS image links, unless you provide the source as a Base64 data image.

{
  "action": "edit",
  "prompt": "Add a sunset sky while preserving the main subject",
  "image_urls": ["https://example.com/source-image.png"],
  "model": "nano-banana-pro",
  "count": 1,
  "aspect_ratio": "16:9",
  "resolution": "2K"
}

The same optional generation controls apply to editing. Select an appropriate model with model, request up to four images through count, and set the desired aspect ratio and resolution when needed. If using nano-banana-2-lite, use only 1K resolution.

Use callbacks for asynchronous completion

Add an optional callback_url when your application needs completion results delivered to a server endpoint. With a callback URL, the API immediately returns a task_id and basic results. When processing completes, it POSTs the full JSON result to the callback URL.

{
  "action": "generate",
  "prompt": "A minimal product illustration",
  "model": "nano-banana-2",
  "count": 2,
  "callback_url": "https://your-service.example/image-callback"
}

The callback payload uses the same response structure, so the receiving service should handle success, task_id, trace_id, and data. Store both task_id and trace_id in your application logs or job records for troubleshooting.

Handle API errors and partial results

Error responses return success as false, an error object containing code and message, plus a trace_id.

{"success": false, "error": {"code": "invalid_token", "message": "..."}, "trace_id": "..."}
  • 400 token_mismatched indicates a token mismatch.
  • 400 api_not_implemented indicates the API is not implemented.
  • 401 invalid_token indicates an invalid token.
  • 403 forbidden means a provider safety policy rejected the request. Rejected calls are not billed.
  • 429 too_many_requests indicates too many requests.
  • 500 api_error indicates an API error.

For multi-image requests, do not assume a single safety rejection means every image failed. Review the returned results, retain the task and trace identifiers, and account for successful images individually. For the complete integration reference, see the Nano Banana Images API documentation.

Comments

Post a Comment

Popular posts from this blog

Artistic QR Code API Integration Guidance

Image
Artistic QR code is an innovative technological product that combines QR codes with beautiful background images, creating practical and visually appealing works. They not only possess the functionality of traditional QR codes, allowing quick scanning and recognition by smart devices, but also incorporate artistic elements to enhance visual appeal and brand recognition. Some artistic QR codes are even generated by artificial intelligence, fully leveraging modern technology to demonstrate unparalleled innovation and uniqueness. This makes artistic QR codes widely applicable in areas such as brand marketing and advertising. In simple terms, artistic QR codes are the perfect combination of QR code scanning and artistic aesthetics. They not only provide the function of information transmission, but also enhance the user's visual experience, making each scan a delightful artistic enjoyment. Overview of Artworks Let's take a look at a few QR code works: How are they? These are ar...
Read more

How to Configure Claude Code with CC Switch and Ace Data Cloud

Image
If you use Claude Code across a terminal, VS Code, or remote development setup, the awkward part is often not the model itself but the configuration: where should requests go, where should the token live, and how do you switch providers without editing files by hand? This guide walks through a practical setup using CC Switch as the graphical configuration manager and Ace Data Cloud as the Anthropic-compatible base URL. The goal is simple: configure Claude Code once, verify the active endpoint, and keep the setup easy to change later. What you can do With the setup described in the Ace Data Cloud documentation, you can: Manage Claude Code provider configuration through a desktop UI instead of manually editing settings.json . Store an Ace Data Cloud provider with ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN . Switch the active Claude Code provider from CC Switch without rewriting your configuration every time. Use the same provider configuration from the terminal an...
Read more

How to Build a Server-Side Image Editing Workflow with GPT-Image-2

Image
If your product needs image editing, the hard part is rarely the model call itself. The real challenge is building a reliable workflow around user images, reference assets, predictable output sizes, and slow-running jobs without forcing every file through a manual upload step. This guide walks through a practical server-side workflow using the OpenAI Images Edits API on Ace Data Cloud. The focus is gpt-image-2 , because the documented editing flow supports direct image URLs, base64 input, multiple reference images, high-resolution output through size , and asynchronous callbacks. What you can do The edits endpoint is designed for turning one or more input images plus an instruction into a modified output image. In practical terms, you can use it to: Convert an existing infographic or poster into a different visual theme while preserving its layout. Change a product, shelf, room, or object style while keeping the original arrangement stable. Pass image URLs directly f...
Read more