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#

bash

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#

ModelBest Fornano-bananaStandard image generation (default)nano-banana-2-liteFast, lightweight second-generation modelnano-banana-2Improved quality, second generationnano-banana-2.1Latest efficient model; 1K, 2K, and 4K generation and editingnano-banana-proHighest quality, most detailed outputnano-banana:officialOfficial channel variant of nano-banana``nano-banana-2-lite:officialOfficial channel variant of nano-banana-2-lite``nano-banana-2:officialOfficial channel variant of nano-banana-2``nano-banana-pro:officialOfficial channel variant of nano-banana-pro

Workflows#

1. Text-to-Image#

json

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.

json

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#

ParameterValuesDescriptionaction``"generate", "edit"Operation modemodel``"nano-banana", "nano-banana-2-lite", "nano-banana-2", "nano-banana-2.1", "nano-banana-pro", "nano-banana:official", "nano-banana-2-lite:official", "nano-banana-2:official", "nano-banana-pro:official"Model to use; 2.1 has no :official variantpromptstringImage description or editing instructionimage_urlsarray of stringsSource image URLs (required for edit action)aspect_ratio``"1:1", "3:2", "2:3", "16:9", "9:16", "4:3", "3:4"Output aspect ratioresolution``"1K", "2K", "4K"Default 1K; nano-banana and nano-banana-2-lite support only 1K; 2, 2.1, and Pro support all three resolutionscallback_urlstringAsync callback URL; returns a task ID immediately

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