NanoBanana Image Generation

Generate and edit AI images through AceDataCloud's NanoBanana (Gemini-based) API.

First-time setup

1. Install the official Skill with clawhub install @acedatacloud/nano-banana. Check that the ClawHub publisher is @acedatacloud.
2. Sign in at AceDataCloud → Applications, open General application, and check Nano Banana access, balance, and current pricing. Copy its API key, or select Manage Keys → Create for a separate key. Copy the key value without Bearer ; a platform-... management token is not a service API key.
3. If you enable Allowed APIs restrictions, include /nano-banana/images and /nano-banana/tasks. Advanced workflows below may call additional routes.
4. On the OpenClaw Gateway host, put ACEDATACLOUD_API_TOKEN=your_api_key_here in ~/.openclaw/.env, then restart the Gateway and start a new session. For a direct terminal test, run export ACEDATACLOUD_API_TOKEN="your_api_key_here" in that shell. Never put the key in a prompt or commit an .env file.
5. Run the Quick Start below. If this workflow returns a task ID, query that same task until it finishes; do not submit the same billable request again just to check progress.

Illustrated key setup, first run, and troubleshooting · Token details

Quick Start

curl -X POST https://api.acedata.cloud/nano-banana/images \
  -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action": "generate", "prompt": "a watercolor painting of a French countryside village", "model": "nano-banana"}'

Async: See async task polling. Poll via POST /nano-banana/tasks with {"id": "..."}.

Models

Workflows

1. Text-to-Image

POST /nano-banana/images
{
  "action": "generate",
  "prompt": "a photorealistic macro shot of morning dew on a spider web",
  "model": "nano-banana-2.1",
  "aspect_ratio": "16:9",
  "resolution": "2K"
}

2. Image Editing

Edit existing images using natural language instructions — no mask needed. Pass source images via image_urls.

POST /nano-banana/images
{
  "action": "edit",
  "prompt": "change the background to a starry night sky",
  "image_urls": ["https://example.com/photo.jpg"],
  "model": "nano-banana-2.1",
  "resolution": "2K"
}

Parameters

To use 2.1, explicitly set model:"nano-banana-2.1"; omitting model still selects nano-banana. For nonblocking requests, set async:true, retain task_id, and poll /nano-banana/tasks to terminal success before returning an image. No nano-banana-2.1:official variant is published.

The same 2.1 model is also accepted by POST /openai/images/generations (public alias /v1/images/generations) and POST /openai/images/edits (public alias /v1/images/edits). Those use their own OpenAI-compatible schemas (image for JSON editing, not image_urls; size rather than this endpoint's resolution/aspect_ratio). Check that endpoint's current schema before reusing a request; do not assume identical response fields. Prices depend on the current service/package; consult live pricing rather than hard-coding a per-call USD amount.

Gotchas

• Editing does NOT require a mask — just describe the change in natural language
• Editing uses the same /nano-banana/images endpoint with action: "edit" and image_urls array (not a separate /edit path)
• nano-banana-2.1 supports 1K, 2K, and 4K; nano-banana-pro offers the highest quality
• :official variants (e.g., nano-banana:official) route through the official channel
• Task polling uses id (not task_id) in the /nano-banana/tasks request body
• Aspect ratio uses colon notation (e.g., "16:9") not pixel dimensions
• The Gemini-based model excels at understanding complex, conversational editing instructions

MCP: pip install mcp-nano-banana | Hosted: https://nanobanana.mcp.acedata.cloud/mcp | See all MCP servers