How to Build Image Generation and Editing Workflows with the Nano Banana Images API
Image features are easy to prototype and surprisingly easy to make messy in production: one endpoint may generate assets, another may edit them, and a third may be needed to track long-running work. The Nano Banana Images API keeps that workflow compact by using one endpoint for both text-to-image generation and image editing.
What you can do
The API exposes a single HTTP interface at POST /nano-banana/images on the base URL https://api.acedata.cloud. The request body chooses the workflow with action:
generatecreates images from a textprompt.editedits one or more existing images usingimage_urlsplus a textprompt.callback_urlcan be added when you want the result delivered to your own webhook instead of holding a long connection open.task_idandtrace_idare returned so you can associate results with your own jobs and troubleshoot failures.
The same endpoint can support product mockups, social image variants, visual content generation, image composition, or a small internal tool where a designer submits a prompt and a few reference images.
How it works
Every request uses JSON over HTTP. Authentication is sent with the authorization: Bearer {token} header, and the recommended request headers are accept: application/json and content-type: application/json.
For a generation request, the minimum body is action and prompt. For an editing request, you still send action and prompt, but you also include image_urls, an array of one or more publicly accessible HTTP or HTTPS image URLs. The documentation also notes that Base64 data URLs can be used for image input.
The optional model field controls which Nano Banana model variant is used. The documented options include nano-banana as the default, nano-banana-2-lite, nano-banana-2, nano-banana-pro, and matching :official channel versions. Other optional controls include count, aspect_ratio, resolution, and callback_url.
Start with a small generate request
A good first implementation is a thin server-side wrapper. Keep the user-facing form simple: a prompt input, a model selector if you need it, and perhaps a count field. The API supports count from 1 to 4, with a default of 1. Each image is generated by an independent call, and ordinary technical failures or provider security refusals affect only the corresponding call while successful images can 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 developer dashboard showing an image workflow, deep navy UI, terminal panel, API card, soft glow, modern SaaS style.",
"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. Store the image URL as the asset you will show to the user, and store the two IDs in your job table.
{
"success": true,
"task_id": "70e6931b-6e34-43db-9e36-8765e2809d04",
"trace_id": "60df8d38-f265-4986-aec7-75c9220bced2",
"data": [
{
"prompt": "A clean developer dashboard showing an image workflow...",
"image_url": "https://platform2.cdn.acedata.cloud/nanobanana/1d0160b4-93f9-4229-8926-ea9ef0bed336.png"
}
]
}Edit existing images with references
The editing flow is useful when the user starts from assets they already have: a product shot, a character image, a logo, a clothing reference, or a layout mock. Set action to edit, pass the reference images in image_urls, and describe the intended transformation in prompt.
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 logo on the dashboard header and keep the UI clean and readable.",
"image_urls": [
"https://cdn.acedata.cloud/1mma4f.png"
],
"count": 1
}
resp = requests.post(url, json=payload, headers=headers)
print(resp.json())In production, validate that every URL is reachable before calling the API. The documented requirement is that image_urls must be direct, publicly accessible links, with HTTPS recommended.
Use callbacks for longer jobs
Image generation and editing may take time. If your app is a web dashboard, a queue worker, or an automation pipeline, adding callback_url is usually cleaner than keeping a request open. The API can immediately return a response containing the task_id, then send the complete JSON to your webhook with POST when the task completes.
On your side, treat task_id as the external job identifier. When the webhook arrives, match it to your local record, read data[].image_url, and mark the job complete. Keep trace_id in logs so debugging has a shared reference.
Handle errors deliberately
The documented error format returns success: false, an error object, and trace_id. Common codes include invalid_token for authentication failure, too_many_requests for request frequency limits, forbidden when a provider security policy denies the request or generated result, and api_error for server exceptions.
A practical integration should branch on these codes. Authentication failures should not be retried blindly. Rate limits should back off. A provider security refusal should be shown as a content-specific rejection rather than a generic outage. Server exceptions should be logged with trace_id and retried only under your normal retry policy.
Putting it together
The nice part of this API shape is that generation, editing, synchronous responses, and webhook-based workflows all share one mental model: send action, send a prompt, optionally send image inputs and workflow controls, then read data[].image_url. That makes it straightforward to build a small image tool first, and later move the same request shape into a queue, an internal CMS, or an automated content pipeline.
For the complete field list and examples, read the Nano Banana Images API documentation.
Comments
Post a Comment