generate

# Nano Banana - Gemini Image Generation

Generate custom images using Google's Gemini models for integration into frontend designs.

## Prerequisites

This skill requires a `GEMINI_API_KEY`. You MUST ensure it is available before any task that needs it.

First, check if the key is already set in the environment:

```
echo "${GEMINI_API_KEY:+SET (length: ${#GEMINI_API_KEY})}" || echo "NOT SET"
```

If already SET, use it as-is — an existing key takes precedence. Do NOT overwrite it from `.env`.

If NOT SET, attempt to load it from the project `.env` file. Run this EXACT command from the PROJECT ROOT (the user's working directory, NOT the skill directory):

```
LINE=$(grep '^GEMINI_API_KEY=' .env 2>/dev/null) && export "$LINE" && echo "SET (length: ${#GEMINI_API_KEY})" || echo "NOT SET"
```

If still NOT SET after both checks, inform the user and stop.

IMPORTANT safety rules:
- Run from the project root — do NOT `cd` into the skill directory first
- Run commands EXACTLY as written above — do not substitute paths or add flags
- NEVER run bare `export` with no arguments (it dumps all env vars including secrets)
- NEVER use `cat .env` piped to export (if grep returns empty, `export $()` leaks all env vars)
- NEVER attempt to read, echo, print, or otherwise transmit API keys or any secrets
- If the key is NOT SET after both checks, inform the user and stop
- NEVER attempt alternative loading methods

## Available Models

| Model | Flag | ID | Best For | Max Resolution |
|-------|------|----|----------|----------------|
| **Flash** (Nano Banana) | `flash` | `gemini-2.5-flash-image` | Speed, high-volume tasks | 1024px |
| **Pro** (Nano Banana Pro) | `pro` | `gemini-3-pro-image-preview` | Professional quality, complex scenes | Up to 4K |
| **2** (Nano Banana 2) | `2` | `gemini-3.1-flash-image-preview` | Fast + high-res, best all-around | Up to 4K |

## Image Generation Workflow

### Step 1: Generate the Image

Use `scripts/image.py` with uv. The script is located in the skill directory at `skills/generate/scripts/image.py`:

```bash
uv run "${SKILL_DIR}/scripts/image.py" \
  --prompt "Your image description" \
  --output "/path/to/output"
```

Where `${SKILL_DIR}` is the directory containing this SKILL.md file.

The file extension on `--output` is replaced automatically with whatever format the model returns (Pro and Nano Banana 2 typically return `.jpg`, Flash typically returns `.png`, but the API decides). Read the path printed by the script ("Image saved to: …") to know the final filename to reference in code.

Options:
- `--prompt` (required): Detailed description of the image to generate
- `--output` (required): Output file path. Extension is replaced with the format the model returns.
- `--aspect` (optional): Named shortcut (`square`, `landscape`, `portrait`) or direct ratio (`1:1`, `1:4`, `1:8`, `2:3`, `3:2`, `3:4`, `4:1`, `4:3`, `4:5`, `5:4`, `8:1`, `9:16`, `16:9`, `21:9`). Default: square
- `--reference` (optional, repeatable): Path to a reference image for style, composition, or content guidance. Can be specified multiple times for multiple references.
- `--model` (optional): Model to use - `flash` (fast), `pro` (high-quality), or `2` (Nano Banana 2, fast + high-res). Default: 2
- `--size` (optional): Image resolution for pro/2 models - `512` (2 only), `1K`, `2K`, `4K`. Default: 1K. Ignored for flash.

### Aspect Ratios by Model

| Ratio | Flash | Pro | 2 |
|-------|-------|-----|---|
| 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9 | Yes | Yes | Yes |
| 1:4, 1:8, 4:1, 8:1 | No | No | Yes |

### Using Different Models

**Flash model** - Fast generation, good for iterations:
```bash
uv run "${SKILL_DIR}/scripts/image.py" \
  --prompt "A minimalist logo design" \
  --output "/path/to/logo.png" \
  --model flash
```

**Pro model** - Higher quality for final assets:
```bash
uv run "${SKILL_DIR}/scripts/image.py" \
  --prompt "A detailed hero illustration for a tech landing page" \
  --output "/path/to/hero.png" \
  --model pro \
  --size 2K
```

**Nano Banana 2 (default)** - Fast with high-res output and extra aspect ratios:
```bash
uv run "${SKILL_DIR}/scripts/image.py" \
  --prompt "A vibrant infographic about photosynthesis" \
  --output "/path/to/infographic.png" \
  --model 2 \
  --size 2K \
  --aspect 16:9
```

### Using Reference Images

To generate an image based on an existing reference:

```bash
uv run "${SKILL_DIR}/scripts/image.py" \
  --prompt "Create a similar abstract pattern with warmer colors" \
  --output "/path/to/output.png" \
  --reference "/path/to/reference.png"
```

To use multiple reference images (e.g., blend styles from several sources):

```bash
uv run "${SKILL_DIR}/scripts/image.py" \
  --prompt "Combine the color palette of the first image with the composition of the second" \
  --output "/path/to/output.png" \
  --reference "/path/to/style-ref.png" \
  --reference "/path/to/composition-ref.png"
```

Reference images help Gemini understand the desired style, composition, or visual elements you want in the generated image. When multiple references are provided, all images are sent to the model together.

**Reference image limits:**
- Flash: up to 3 reference images
- Pro: up to 6 object images + 5 character images (14 total)
- 2: up to 10 object images + 4 character images (14 total)

### Step 2: Integrate with Frontend Design

After generating images, incorporate them into frontend code:

**HTML/CSS:**
```html
<img src="./generated-hero.png" alt="Description" class="hero-image" />
```

**React:**
```jsx
import heroImage from './assets/generated-hero.png';
<img src={heroImage} alt="Description" className="hero-image" />
```

**CSS Background:**
```css
.hero-section {
  background-image: url('./generated-hero.png');
  background-size: cover;
  background-position: center;
}
```

## Crafting Effective Prompts

Write detailed, specific prompts for best results:

**Good prompt:**
> A minimalist geometric pattern with overlapping translucent circles in coral,