nano-banana-image — Claude Code skill: what it does, how to install
nano-banana-image is a skill for generating and editing images through AceDataCloud's API, using text prompts and reference URLs with 1K, 2K, or 4K output.
Apache-2.0 232 installs ★ 17 updated 2026-10-25
npx skills add AceDataCloud/Skills --skill nano-banana-image -a claude-codeWhat nano-banana-image does
The skill wraps a single AceDataCloud endpoint for your agent: POST /nano-banana/images, where action is either generate or edit. With edits you put the source pictures in image_urls and describe the change in plain language, so there is no mask to paint.
Model names run from nano-banana up to nano-banana-pro, and several have an :official variant that goes through the official channel. Size comes from resolution (1K, 2K, 4K), shape from aspect_ratio written as 16:9 rather than pixels. Only 1K works on nano-banana and nano-banana-2-lite, while nano-banana-2, nano-banana-2.1 and nano-banana-pro take all three.
Put ACEDATACLOUD_API_TOKEN into the agent's environment before the first call and make sure the host reaches api.acedata.cloud over HTTPS. A platform-... management token will not authenticate; you need the service API key from the AceDataCloud console. Leaving model out still routes to nano-banana, so name nano-banana-2.1 explicitly when that is the one you want. Async replies hand back a task id that you poll on POST /nano-banana/tasks under the key id, not task_id.
What it helps with
- generate a 16:9 cover image from a text prompt
- swap the background on a photo without painting a mask
- render the same scene at 4K
- compare two models on one prompt
- poll an async job until the picture is ready
Example prompts for the agent
- Generate a watercolour village scene with
nano-banana-2.1, 16:9, 2K. - Edit the photo in
image_urlsand turn the sky into a starry night. - Send it async and poll the task by
iduntil it finishes.
How to install nano-banana-image
1Skills CLI (Vercel)
npx skills add AceDataCloud/Skills --skill nano-banana-image -a claude-code2Manually: put the files in place
~/.claude/skills/nano-banana-image/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/nano-banana-image/
1Skills CLI (Vercel)
npx skills add AceDataCloud/Skills --skill nano-banana-image -a codex2Manually: put the files in place
.agents/skills/nano-banana-image/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add AceDataCloud/Skills --skill nano-banana-image -a cursor2Manually: put the files in place
.cursor/skills/nano-banana-image/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install AceDataCloud/Skills skills/nano-banana-image2Manually: put the files in place
.github/skills/nano-banana-image/SKILL.md1Skills CLI (Vercel)
npx skills add AceDataCloud/Skills --skill nano-banana-image -a gemini-cli2Platform CLI
gemini skills install https://github.com/AceDataCloud/Skills --path skills/nano-banana-imageManually: put the files in place
.devin/skills/nano-banana-image/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add AceDataCloud/Skills --skill nano-banana-image -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about nano-banana-image
How do I install nano-banana-image in Claude Code?
Run npx skills add AceDataCloud/Skills --skill nano-banana-image -a claude-code. The skill lands at ~/.claude/skills/nano-banana-image/SKILL.md.
What does nano-banana-image do?
It gives the agent text-to-image generation and natural-language editing of existing pictures through AceDataCloud's NanoBanana models. Editing takes a written instruction plus the source image URLs.
What is required before the first request?
An ACEDATACLOUD_API_TOKEN holding a service API key from the AceDataCloud console, plus HTTPS access to api.acedata.cloud.
Source text
SKILL.md · Apache-2.0
---
name: nano-banana-image
description: Nano Banana image by Ace Data Cloud. Generate and edit images with Nano Banana, Nano Banana 2.1 or Pro. Use when the user asks for Nano Banana or NanoBanana image generation, reference-image editing or 1K, 2K and 4K output.
license: Apache-2.0
metadata:
author: acedatacloud
version: "1.0"
compatibility: Requires ACEDATACLOUD_API_TOKEN in the agent process environment and HTTPS access to api.acedata.cloud. See README.md for installation and key setup.
---
# Nano Banana by Ace Data Cloud
Generate and edit AI images through AceDataCloud's NanoBanana (Gemini-based) API.
## Install and connect from skills.sh
This integration is maintained by **Ace Data Cloud**; it is not an official Nano Banana publisher listing. Install only this Skill with `npx skills add acedatacloud/skills --skill nano-banana-image --yes`, or use the [public skills.sh page](https://skills.sh/acedatacloud/skills/nano-banana-image). Keep the slug `nano-banana-image` when selecting it.
Read the [illustrated first-run guide](README.md) ([简体中文](readme.zh-CN.md)) for registration, **Applications → General application**, API key access and price checks, and the environment variable location for your coding agent. For skills.sh installations, use this guide; any ClawHub-specific setup applies only to OpenClaw. The shared references linked here are online because focused installs do not include sibling `_shared/` folders.
## ClawHub / OpenClaw 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](https://platform.acedata.cloud/console/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](https://github.com/AceDataCloud/Skills#first-run-with-clawhub-and-openclaw) · [Token details](https://github.com/AceDataCloud/Skills/blob/main/skills/_shared/authentication.md)
## 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](https://github.com/AceDataCloud/Skills/blob/main/skills/_shared/async-tasks.md). Poll via `POST /nano-banana/tasks` with `{"id": "..."}`.
## Models
| Model | Best For |
|-------|----------|
| `nano-banana` | Standard image generation (default) |
| `nano-banana-2-lite` | Fast, lightweight second-generation model |
| `nano-banana-2` | Improved quality, second generation |
| `nano-banana-2.1` | Latest efficient model; 1K, 2K, and 4K generation and editing |
| `nano-banana-pro` | Highest quality, most detailed output |
| `nano-banana:official` | Official channel variant of `nano-banana` |
| `nano-banana-2-lite:official` | Official channel variant of `nano-banana-2-lite` |
| `nano-banana-2:official` | Official channel variant of `nano-banana-2` |
| `nano-banana-pro:official` | Official 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
| Parameter | Values | Description |
|-----------|--------|-------------|
| `action` | `"generate"`, `"edit"` | Operation mode |
| `model` | `"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` variant |
| `prompt` | string | Image description or editing instruction |
| `image_urls` | array of strings | Source image URLs (required for edit action) |
| `aspect_ratio` | `"1:1"`, `"3:2"`, `"2:3"`, `"16:9"`, `"9:16"`, `"4:3"`, `"3:4"` | Output aspect ratio |
| `resolution` | `"1K"`, `"2K"`, `"4K"` | Default 1K; `nano-banana` and `nano-banana-2-lite` support only 1K; 2, 2.1, and Pro support all three resolutions |
| `callback_url` | string | Async 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](https://github.com/AceDataCloud/Skills/blob/main/skills/_shared/mcp-servers.md)
© acedatacloud · Apache-2.0 · AceDataCloud/Skills