Skill: coolhackboy/poyo-nano-banana-2 (version 1.0.2)

--- name: poyo-nano-banana-2 description: Nano Banana 2 image generation and advanced editing on PoYo / poyo.ai via `https://api.poyo.ai/api/generate/submit`; use for `nano-banana-2-new`, `nano-banana-2-new-edit`, multi-reference workflows, text-to-image, image-to-image, and 1K/2K/4K output. metadata: {"openclaw":{"homepage":"https://docs.poyo.ai/api-manual/image-series/nano-banana-2-new","requires":{"bins":["curl"],"env":["POYO_API_KEY"]},"primaryEnv":"POYO_API_KEY"}} --- # PoYo Nano Banana 2 Image Generation and Advanced Editing Use this skill for Nano Banana 2 jobs on PoYo. It fits multi-reference generation, advanced editing, and higher-resolution output; read `references/frontend-notes.md` when product-side defaults matter. ## Use When - The user explicitly asks for `Nano Banana 2`, `nano-banana-2-new`, or `nano-banana-2-new-edit`. - The task depends on multiple reference images, image composition, or advanced edits. - The workflow needs `1K`, `2K`, or `4K` output, or may use `google_search`. ## Model Selection - `nano-banana-2-new`: text-to-image and image-to-image entry point. - `nano-banana-2-new-edit`: use whenever the user explicitly wants to edit supplied images. ## Key Inputs - `prompt` is required and limited to 1000 chars. - `image_urls` supports up to 14 reference images. - `size` supports `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`. - `resolution` supports `1K`, `2K`, `4K` and defaults to `1K`. - `google_search` is optional and only useful for real-world grounding. ## Execution - Read `references/api.md` for payload fields, examples, and polling notes. - Read `references/frontend-notes.md` when you need product-side defaults or want to mirror the current desktop frontend behavior. - Use `scripts/submit_nano_banana_2.sh` to submit a task from the shell when direct API execution is appropriate. - If the user needs a raw curl example, adapt one from `references/api.md`. - After submission, report the `task_id` clearly so follow-up polling is easy. ## Output expectations When helping with a Nano Banana 2 task, include: - chosen model - final payload or summarized parameters - whether reference images are used - returned `task_id` if the request was actually submitted - next step: poll status or wait for webhook

path: scripts/submit_nano_banana_2.sh
content: #!/usr/bin/env bash
set -euo pipefail

if [[ $# -lt 1 ]]; then
  cat <<'EOF' >&2
Usage:
  POYO_API_KEY=... submit_nano_banana_2.sh <payload.json>
  submit_nano_banana_2.sh <api_key> <payload.json>

Examples:
  POYO_API_KEY="$POYO_API_KEY" submit_nano_banana_2.sh payload.json
  submit_nano_banana_2.sh "$POYO_API_KEY" payload.json
EOF
  exit 1
fi

if [[ $# -eq 1 ]]; then
  : "${POYO_API_KEY:?POYO_API_KEY is required when api_key is not passed explicitly}"
  [REDACTED_SECRET]"
  payload_file="$1"
else
  api_key="$1"
  payload_file="$2"
fi

curl -sS https://api.poyo.ai/api/generate/submit \
  -H "Authorization: Bearer ${api_key}" \
  -H 'Content-Type: application/json' \
  --data @"${payload_file}"


path: references/frontend-notes.md
content: # Frontend implementation notes from desktop `poyoapi`

These notes come from the local desktop frontend at `/Users/ronny/Desktop/poyoapi`.

## Relevant files

- `components/tool/nano-banana-2/index.tsx`
- `services/nanobananaService.ts`
- `data/models.json`
- `app/[locale]/models/nano-banana-2-api/ClientPage.tsx`

## What the frontend actually does

### Request flow

1. Upload user images first and obtain public URLs.
2. Submit `POST /api/generate/submit` with a JSON body.
3. Read `response.data.task_id`.
4. Poll `GET /api/generate/status/{task_id}` every 3 seconds until `finished` or `failed`.

### Supported models in the shared component

The frontend component knows about these model ids:

- `nano-banana-2-new`
- `nano-banana-2-new-edit`
- `nano-banana-2`
- `nano-banana-2-edit`
- `nano-banana`
- `nano-banana-edit`

For this skill, prefer the newer documented pair:

- `nano-banana-2-new`
- `nano-banana-2-new-edit`

### Frontend capability map

For the newer pair, the UI enables:

- `resolution`: yes
- `google_search`: yes
- `mask`: no
- reference images on edit model: yes
- max reference images for `nano-banana-2-new-edit`: 14

### Frontend file validation

Reference image uploads are validated as:

- max file size: 10 MB
- allowed MIME types: `image/jpeg`, `image/png`, `image/webp`

The component also contains mask-upload code for other model families, but Nano Banana 2 New currently has no mask capability enabled.

### Default UX choices in the frontend

- default prompt: `Generate image：Nano Banana 2 API is now available on Poyo.ai`
- default resolution: `1K`
- default aspect ratio: `16:9`
- status polling interval: 3 seconds

## Product/marketing copy used by the frontend

`data/models.json` describes Nano Banana Pro as:

- provider: Google
- tasks: Text to Image, Image to Image
- positioning: advanced Gemini image model with 4K output, stronger reasoning, real-time data integration, and multi-image composition

That copy is marketing-facing; use API docs as the source of truth for technical behavior.

## Practical guidance for skill users

- If a user provides local images, upload them somewhere reachable first, then pass URL(s) in `input.image_urls`.
- If the request is edit-oriented, require at least one source image.
- Polling every ~3 seconds matches the current frontend implementation.
- Prefer `16:9` for general demos because the PoYo frontend uses that default.


path: references/api.md
content: # PoYo Nano Banana 2 API Reference

## Endpoint

- Submit task: `POST https://api.poyo.ai/api/generate/submit`
- Status query: see PoYo unified task status docs at <https://docs.poyo.ai/api-manual/task-management/status>
- Model page: <https://poyo.ai/models/nano-banana-2>
- Source docs: <https://docs.poyo.ai/api-manual/image-series/nano-banana-2-new>

## Auth

Send:

```http
[REDACTED_SECRET]
Content-Type: application/json
```

Get API keys from <https://poyo.ai/dashboard/api-key>.

Recommended skill env var:

- `POYO_API_KEY`

## Models

- `nano-banana-2-new`: text-to-image and image-to-image generation
- `nano-banana-2-new-edit`: advanced image editing

## Request schema

Top-level fields:

- `model` string, required
- `callback_url` string URI, optional
- `input` object

`input` fields:

- `prompt` string, required, max 1000 chars
- `image_urls` string[] URI, optional, supports up to 14 reference images
- `size` enum, optional: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`
- `resolution` enum, optional: `1K`, `2K`, `4K` (default `1K`)
- `google_search` boolean, optional

## Submission example

```bash
curl -sS https://api.poyo.ai/api/generate/submit \
  -H '[REDACTED_SECRET]' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "nano-banana-2-new",
    "input": {
      "prompt": "A cyberpunk street scene with neon signs and rain",
      "size": "16:9",
      "resolution": "2K"
    }
  }'
```

## Edit example

```bash
curl -sS https://api.poyo.ai/api/generate/submit \
  -H '[REDACTED_SECRET]' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "nano-banana-2-new-edit",
    "input": {
      "prompt": "Add colorful flowers in the foreground",
      "image_urls": ["https://example.com/landscape.jpg"],
      "size": "16:9",
      "resolution": "2K"
    }
  }'
```

## Typical response

```json
{
  "code": 200,
  "data": {
    "task_id": "task-unified-1757165031-uyujaw3d",
    "status": "not_started",
    "created_time": "2025-11-12T10:30:00"
  }
}
```

## Polling notes

- Save `task_id` immediately.
- If `callback_url` is provided, PoYo sends a POST callback when status becomes `finished` or `failed`.
- Even with callbacks, the user can still query unified task status directly.

## Error patterns

### 400

```json
{
  "code": 400,
  "error": {
    "message": "Invalid request parameters",
    "type": "invalid_request_error"
  }
}
```

### 401

```json
{
  "code": 401,
  "error": {
    "message": "Unauthorized - Invalid API key",
    "type": "authentication_error"
  }
}
```

## Practical guidance

- Use `nano-banana-2-new-edit` whenever the user explicitly wants to modify a supplied image.
- Use `image_urls` only when the request truly depends on source/reference images.
- Prefer `2K` for a balance of quality and cost unless the user explicitly asks for `4K`.
- Prefer `16:9` for banners/screens, `1:1` for avatars/posts, and `9:16` for stories/mobile.
- If a user asks for factual real-world grounding, consider `google_search: true`.


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