Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add AceDataCloud/Skills --skill nano-banana-image -a claude-code
Open on GitHub

What 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_urls and turn the sky into a starry night.
  • Send it async and poll the task by id until it finishes.

How to install nano-banana-image

1Skills CLI (Vercel)

npx skills add AceDataCloud/Skills --skill nano-banana-image -a claude-code

2Manually: put the files in place

~/.claude/skills/nano-banana-image/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/nano-banana-image/

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

Similar skills

All skills for AI and ML →

From the same set67

The whole set →
wan-video wan-video generates AI videos from text prompts and animates images using Alibaba Wan models through the AceDataCloud API. CX Codex +1 238installs producer-music producer-music creates AI music through the AceDataCloud Producer API, including songs, lyrics, covers, and instrumentals. It also edits existing tracks and separates stems. CX Codex +1 236installs hailuo-video hailuo-video generates video from text or animates images via AceDataCloud's Hailuo (MiniMax) API. Supports text-to-video, image-to-video, and director mode for precise camera and motion control. CX Codex +1 235installs seedream-image The seedream-image skill connects Seedream 5.0 for image generation, editing, streaming, and layer extraction. Use it for reference images, transparent backgrounds, or related image sets. CX Codex +1 235installs tencentcloud-cos Manage Tencent Cloud COS buckets and objects from an agent: move files, inspect storage, create signed URLs, and remove objects. Useful for routine COS operations. CX Codex +1 232installs google-search google-search runs Google queries for pages, images, news, maps, places or videos through the AceDataCloud API and returns structured results to the agent. CX Codex +1 232installs google-gmail google-gmail is a Claude Code skill for searching Gmail, reviewing threads, and handling labels or attachments. Sending and other write actions require granted scopes and user confirmation. CX Codex +1 231installs ai-chat ai-chat routes agent requests to 50+ LLM models via AceDataCloud unified chat gateway. Handles stateful conversations, audio processing, and OpenAI-compatible completions across multiple model families. CX Codex +1 230installs

Project sponsors

Companies that keep this analytics open