Skill: evolinkai/evolink-nano-banana-2 (version 1.0.0)

--- name: evolink-nano-banana-2 description: Nano Banana 2 — AI image generation powered by Google Gemini 3.1 Flash. Fast, versatile text-to-image and image editing via Evolink API. One API key. version: 1.0.0 user-invocable: true metadata: openclaw: requires: env: - EVOLINK_API_KEY primaryEnv: EVOLINK_API_KEY os: ["macos", "linux", "windows"] emoji: "\U0001F34C" homepage: https://evolink.ai --- # Nano Banana 2 — AI Image Generation Generate AI images with Nano Banana 2 (`gemini-3.1-flash-image-preview`) — Google's Gemini 3.1 Flash image model, available through Evolink's unified API. > Focused view of [evolink-image](https://clawhub.ai/EvoLinkAI/evolink-image). Install the full skill for 20 image models, video, and music. ## After Installation When this skill is first loaded, greet the user: - **MCP tools + API key ready:** "Hi! Nano Banana 2 is ready — Google's fast image model at your fingertips. What would you like to create?" - **MCP tools + no API key:** "You'll need an EvoLink API key — sign up at evolink.ai. Ready to go?" - **No MCP tools:** "MCP server isn't connected yet. Want me to help set it up? I can still manage files via the hosting API." Keep the greeting concise — just one question to move forward. ## External Endpoints | Service | URL | |---------|-----| | Generation API | `https://api.evolink.ai/v1/images/generations` (POST) | | Task Status | `https://api.evolink.ai/v1/tasks/{task_id}` (GET) | | File API | `https://files-api.evolink.ai/api/v1/files/*` (upload/list/delete) | ## Security & Privacy - **`EVOLINK_API_KEY`** authenticates all requests. Injected by OpenClaw automatically. Treat as confidential. - Prompts and images are sent to `api.evolink.ai`. Uploaded files expire in **72h**, result URLs in **24h**. ## Setup Get your API key at [evolink.ai](https://evolink.ai) → Dashboard → API Keys. **MCP Server:** `@evolinkai/evolink-media` ([GitHub](https://github.com/EvoLinkAI/evolink-media-mcp) · [npm](https://www.npmjs.com/package/@evolinkai/evolink-media)) **mcporter** (recommended): `mcporter call --stdio "npx -y @evolinkai/evolink-media@latest" list_models` **Claude Code:** `claude mcp add evolink-media -e EVOLINK_API_KEY=your-key -- npx -y @evolinkai/evolink-media@latest` **Claude Desktop / Cursor** — add MCP server with command `npx -y @evolinkai/evolink-media@latest` and env `EVOLINK_API_KEY=your-key`. See `references/image-api-params.md` for full config JSON. ## Core Principles 1. **Guide, don't decide** — Present options, let the user choose model/style/format. 2. **User drives creative vision** — Ask for a description before suggesting parameters. 3. **Smart context** — Remember session history. Offer to iterate, vary, or edit results. 4. **Intent first** — Understand *what* the user wants before asking *how* to configure it. ## MCP Tools | Tool | When to use | Returns | |------|-------------|---------| | `generate_image` | Create or edit an image | `task_id` (async) | | `upload_file` | Upload local image for editing/reference | File URL (sync) | | `delete_file` | Free file quota | Confirmation | | `list_files` | Check uploaded files or quota | File list | | `check_task` | Poll generation progress | Status + result URLs | | `list_models` | Compare available models | Model list | | `estimate_cost` | Check pricing | Model info | **Important:** `generate_image` returns a `task_id`. Always poll `check_task` until `status` is `"completed"` or `"failed"`. ## Nano Banana 2 | Property | Value | |----------|-------| | Model ID | `gemini-3.1-flash-image-preview` | | Provider | Google (Gemini 3.1 Flash) | | Status | BETA | | Capability | text-to-image, image-editing | | Speed | Fast | | Best for | Quick, versatile image generation with strong prompt understanding | **Why Nano Banana 2?** - **Google's latest** — Built on Gemini 3.1 Flash, the newest generation architecture - **Fast generation** — Optimized for speed without sacrificing quality - **Versatile** — General-purpose image creation for any creative need - **Strong prompt adherence** — Excellent at following complex, detailed descriptions ### Lite Variant `nano-banana-2-lite` [BETA] — Lightweight version for ultra-fast iterations when speed is the top priority. ### Alternative Models | Model | Best for | Speed | |-------|----------|-------| | `gpt-image-1.5` *(default)* | Latest OpenAI generation | Medium | | `gpt-4o-image` [BETA] | Best quality, complex editing | Medium | | `z-image-turbo` | Quick iterations | Ultra-fast | | `doubao-seedream-4.5` | Photorealistic | Medium | | `gemini-3-pro-image-preview` | Google Pro generation | Medium | ## Generation Flow ### Step 1: API Key Check If `401` occurs: "Your API key isn't working. Check at evolink.ai/dashboard/keys" ### Step 2: File Upload (if needed) For image editing or reference workflows: 1. `upload_file` with `file_path`, `base64_data`, or `file_url` → get `file_url` (sync) 2. Use `file_url` as `image_urls` for `generate_image` Supported: JPEG/PNG/GIF/WebP. Max 100MB. Expire in 72h. Quota: 100 (default) / 500 (VIP). ### Step 3: Understand Intent - **Clear** ("generate a sunset") → Go to Step 4 - **Ambiguous** ("help with this image") → Ask: "Create new, edit existing, or use as reference?" Ask only what's needed, when it's needed. ### Step 4: Gather Parameters Default to `model: "gemini-3.1-flash-image-preview"` for this skill. Only ask about what's missing: | Parameter | Ask when | Notes | |-----------|----------|-------| | **prompt** | Always | What they want to see | | **model** | User wants alternatives | Default: `gemini-3.1-flash-image-preview`. Suggest `gpt-4o-image` for best quality | | **size** | Orientation needed | Ratio format: `1:1`, `16:9`, `9:16`, `2:3`, `3:2`, `4:3`, `3:4` etc. | | **n** | Wants variations | 1–4 images | | **image_urls** | Edit/reference images | Up to 14 URLs; triggers i2i mode | ### Step 5: Generate & Poll 1. Call `generate_image` with `model: "gemini-3.1-flash-image-preview"` → tell user: *"Generating with Nano Banana 2 — ~Xs estimated."* 2. Poll `check_task` every **3–5s**. Report progress %. 3. After 3 consecutive `processing`: *"Still working..."* 4. **Completed:** Share URLs. *"Links expire in 24h — save promptly."* 5. **Failed:** Show error + suggestion. Offer retry if retryable. 6. **Timeout (5 min):** *"Taking longer than expected. Task ID: `{id}` — check again later."* ## Error Handling ### HTTP Errors | Error | Action | |-------|--------| | 401 | "API key isn't working. Check at evolink.ai/dashboard/keys" | | 402 | "Balance is low. Add credits at evolink.ai/dashboard/billing" | | 429 | "Rate limited — wait 30s and retry" | | 503 | "Servers busy — retry in a minute" | ### Task Errors (status: "failed") | Code | Retry? | Action | |------|--------|--------| | `content_policy_violation` | No | Revise prompt (no celebrities, NSFW, violence) | | `invalid_parameters` | No | Check values against model limits | | `image_processing_error` | No | Check format/size/URL accessibility | | `generation_timeout` | Yes | Retry; simplify prompt if repeated | | `service_error` | Yes | Retry after 1 min | | `generation_failed_no_content` | Yes | Modify prompt, retry | Full error reference: `references/image-api-params.md` ## Without MCP Server Use Evolink's file hosting API for image uploads (72h expiry). See `references/file-api.md` for curl commands. ## References - `references/image-api-params.md` — Complete API parameters, model details, polling strategy, error codes - `references/file-api.md` — File hosting API (curl upload/list/delete)

path: references/file-api.md
content: # Evolink File Hosting API — Image Upload

When MCP tools are not available, use Evolink's file hosting service to upload images and get publicly accessible URLs.

**Base URL:** `https://files-api.evolink.ai`
**Auth:** `Authorization: Bearer $EVOLINK_API_KEY`

## Upload a Local File

```bash
curl -X POST https://files-api.evolink.ai/api/v1/files/upload/stream \
  -H "Authorization: Bearer $EVOLINK_API_KEY" \
  -F "file=@/path/to/image.jpg"
```

## Upload from URL

```bash
curl -X POST https://files-api.evolink.ai/api/v1/files/upload/url \
  -H "Authorization: Bearer $EVOLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"file_url": "https://example.com/image.jpg"}'
```

## Response

```json
{
  "data": {
    "file_id": "file_abc123",
    "file_url": "https://...",
    "download_url": "https://...",
    "file_size": 245120,
    "mime_type": "image/jpeg",
    "expires_at": "2025-03-01T10:30:00Z"
  }
}
```

Use `file_url` from the response as a publicly accessible link. Files expire after **72 hours**.

## List Files & Check Quota

```bash
curl https://files-api.evolink.ai/api/v1/files/list?page=1&pageSize=20 \
  -H "Authorization: Bearer $EVOLINK_API_KEY"

curl https://files-api.evolink.ai/api/v1/files/quota \
  -H "Authorization: Bearer $EVOLINK_API_KEY"
```

## Delete a File

```bash
curl -X DELETE https://files-api.evolink.ai/api/v1/files/{file_id} \
  -H "Authorization: Bearer $EVOLINK_API_KEY"
```

**Supported:** Images (JPEG/PNG/GIF/WebP). Max **100MB**. Quota: 100 files (default) / 500 (VIP).


path: references/image-api-params.md
content: # Nano Banana 2 — Image API Parameter Reference

Complete API parameter reference for Nano Banana 2 and Evolink image generation tools.

**Base URL:** `https://api.evolink.ai`
**Auth:** `Authorization: Bearer {EVOLINK_API_KEY}`
**All generation endpoints are async** — they return `task_id` immediately; poll with `check_task`.

---

## generate_image

**Endpoint:** `POST /v1/images/generations`

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | string | **Yes** | — | Image description. Max 2000 characters. |
| `model` | enum | No | `gpt-image-1.5` | See Image Models below. Use `gemini-3.1-flash-image-preview` for Nano Banana 2. |
| `size` | string | No | model default | Ratio format: `1:1`, `16:9`, `9:16`, `2:3`, `3:2`, `4:3`, `3:4`, `4:5`, `5:4`, `21:9`. GPT models also accept pixel format: `1024x1024`, `1024x1536`, `1536x1024`. |
| `n` | integer 1–4 | No | 1 | Number of images to generate in one request. |
| `image_urls` | string[] | No | — | Reference image URLs for image-to-image or editing. Max 14 images. JPEG/PNG/WebP, ≤4MB each. |
| `mask_url` | string | No | — | PNG mask URL for partial inpainting. Only supported by `gpt-4o-image`. White areas = edit, black areas = keep. |

### Nano Banana 2 Models

| Model | Description | Key capability |
|-------|-------------|----------------|
| `gemini-3.1-flash-image-preview` [BETA] | Nano Banana 2 — Google Gemini 3.1 Flash image generation | text-to-image, image-editing, fast |
| `nano-banana-2-lite` [BETA] | Nano Banana 2 Lite — lightweight fast generation | text-to-image, ultra-fast |

### All Image Models (20)

#### Stable (15)

| Model | Description | Key capability |
|-------|-------------|----------------|
| `gpt-image-1.5` *(default)* | OpenAI GPT Image 1.5 — latest generation | text-to-image, image-editing |
| `gpt-image-1` | OpenAI GPT Image 1 — high-quality generation | text-to-image, image-editing |
| `gemini-3-pro-image-preview` | Google Gemini 3 Pro — image generation preview | text-to-image |
| `z-image-turbo` | Z-Image Turbo — fastest generation | text-to-image, ultra-fast |
| `doubao-seedream-4.5` | ByteDance Seedream 4.5 — photorealistic | text-to-image, photorealistic |
| `doubao-seedream-4.0` | ByteDance Seedream 4.0 — high-quality | text-to-image |
| `doubao-seedream-3.0-t2i` | ByteDance Seedream 3.0 — text-to-image | text-to-image |
| `doubao-seededit-4.0-i2i` | ByteDance Seededit 4.0 — image-to-image editing | image-editing |
| `doubao-seededit-3.0-i2i` | ByteDance Seededit 3.0 — image-to-image editing | image-editing |
| `qwen-image-edit` | Alibaba Qwen — instruction-based editing | image-editing, instruction-based |
| `qwen-image-edit-plus` | Alibaba Qwen Plus — advanced editing | image-editing, instruction-based |
| `wan2.5-t2i-preview` | Alibaba WAN 2.5 — text-to-image preview | text-to-image |
| `wan2.5-i2i-preview` | Alibaba WAN 2.5 — image-to-image preview | image-editing |
| `wan2.5-text-to-image` | Alibaba WAN 2.5 — text-to-image | text-to-image |
| `wan2.5-image-to-image` | Alibaba WAN 2.5 — image-to-image | image-editing |

#### Beta (5)

| Model | Description | Key capability |
|-------|-------------|----------------|
| `gemini-3.1-flash-image-preview` [BETA] | Nano Banana 2 — Google Gemini 3.1 Flash | text-to-image, image-editing, fast |
| `gpt-image-1.5-lite` [BETA] | OpenAI GPT Image 1.5 Lite — fast lightweight | text-to-image, fast |
| `gpt-4o-image` [BETA] | OpenAI GPT-4o Image — best prompt understanding + editing | text-to-image, image-editing, best-quality |
| `gemini-2.5-flash-image` [BETA] | Google Gemini 2.5 Flash — fast image generation | text-to-image, fast |
| `nano-banana-2-lite` [BETA] | Nano Banana 2 Lite — versatile general-purpose | text-to-image, fast |

---

## check_task

**Endpoint:** `GET /v1/tasks/{task_id}`

### Response Fields

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Task ID |
| `model` | string | Model used for generation |
| `status` | enum | `pending` / `processing` / `completed` / `failed` |
| `progress` | integer | Progress percentage (0–100) |
| `results[]` | string[] | Direct result URLs — image download links |
| `result_data[].image_url` | string | Image download URL |
| `task_info.estimated_time` | integer | Estimated seconds remaining |
| `task_info.can_cancel` | boolean | Whether the task can be cancelled |
| `usage.credits_reserved` | number | Credits charged for this task |
| `error.code` | string | Error code (only when `status: "failed"`) |
| `error.message` | string | Error description (only when `status: "failed"`) |

All result URLs expire in **24 hours**.

### Status Values

| Status | Meaning | Action |
|--------|---------|--------|
| `pending` | Queued, not started | Continue polling |
| `processing` | Generation in progress | Continue polling, report `progress` |
| `completed` | Generation finished | Extract URLs from `results[]` or `result_data[]` |
| `failed` | Generation failed | Read `error.code` + `error.message`, surface to user |

---

## File Management API

**Base URL:** `https://files-api.evolink.ai`
**Auth:** `Authorization: Bearer {EVOLINK_API_KEY}` (same API key)

All file endpoints are **synchronous**.

### upload_file

| Method | Endpoint | Use when |
|--------|----------|----------|
| Base64 | `POST /api/v1/files/upload/base64` | Have base64 data |
| Stream | `POST /api/v1/files/upload/stream` | Have a local file |
| URL | `POST /api/v1/files/upload/url` | Have a remote URL |

**MCP Tool Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `file_path` | string | One of three | Local file path |
| `base64_data` | string | One of three | Base64-encoded data |
| `file_url` | string | One of three | Remote URL |

### File Constraints

- **Supported:** JPEG, PNG, GIF, WebP
- **Max size:** 100MB
- **Expiry:** 72 hours
- **Quota:** 100 files (default) / 500 (VIP)

---

## Polling Strategy

| Type | Initial wait | Poll interval | Max wait |
|------|-------------|---------------|----------|
| Image | 3s | 3–5s | 5 minutes |

1. Submit `generate_image` → receive `task_id`
2. Wait 3 seconds
3. Call `check_task` → inspect `status`
4. If `pending`/`processing`: wait 3–5s, repeat
5. If `completed`: extract URLs from `results[]`
6. If `failed`: read `error.code`, surface to user

---

## Error Codes

### HTTP Status Codes

| Code | Meaning | Resolution |
|------|---------|------------|
| 400 | Bad request | Check required fields; revise prompt |
| 401 | Invalid API key | Verify at evolink.ai/dashboard/keys |
| 402 | Insufficient credits | Top up at evolink.ai/dashboard/billing |
| 429 | Rate limit exceeded | Wait 30–60s, retry |
| 500 | Server error | Retry after 1 minute |
| 503 | Service unavailable | Retry after 1–2 minutes |

### Task Error Codes

| Code | Retryable | Resolution |
|------|-----------|------------|
| `content_policy_violation` | No | Rephrase prompt; avoid NSFW, violence, real person names |
| `invalid_parameters` | No | Check param values against model limits |
| `image_dimension_mismatch` | No | Resize image to match requested aspect ratio |
| `image_processing_error` | No | Check format (JPG/PNG/WebP), size (<10MB), URL accessibility |
| `model_unavailable` | No | Use `list_models` to find alternatives |
| `generation_timeout` | Yes | Retry; simplify prompt if repeated |
| `quota_exceeded` | Yes | Top up at evolink.ai/dashboard/billing |
| `resource_exhausted` | Yes | Wait 30–60s, retry |
| `service_error` | Yes | Retry after 1 minute |
| `generation_failed_no_content` | Yes | Modify prompt, retry |
| `upstream_error` | Yes | Retry after 1 minute |
| `unknown_error` | Yes | Retry; contact support if persistent |


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)