gpt-image

Files (2)

• SKILL.md
• generate.py · scripts/

SKILL.md (first lines)

# GPT Image 2.5 (fal.ai)

One script drives all four `openai/gpt-image-2.5` endpoints on fal.ai's queue API.

| Endpoint | Reach it with | Best for |
|---|---|---|
| `flare/text-to-image` | *(default)* | **Start here for any new image.** Fast, high quality. Natural lighting, rich textures, complex layouts, transparent backgrounds. |
| `flare/edit` | `--image` | **Start here for any edit.** Changes only what's asked; subject, composition and background survive. References stay recognisable across styles and successive edits. |
| `sunburst/text-to-image` | `--tier sunburst` | Premium hero images. Extra fidelity on intricate detail — fine typography, ornament, texture, product shots. Slower; pay the wait only when detail is the point. |
| `sunburst/edit` | `--tier sunburst --image` | Tightest control. Edits scoped precisely to the instruction, subject and composition preserved across many revision rounds. Reach for it when `flare/edit` drifts. |

Rule of thumb: **flare until it fails you, then sunburst.** Flare is the default for most
work; sunburst buys detail and obedience at the cost of time.

### Choosing between this and the other image skills

- **This skill** — OpenAI-style prompting, transparent backgrounds, masked edits, strong
  in-image typography, sizes pinned to exact pixel dimensions.
- **`fal-image-edit`** (nano-banana-pro / Gemini 3 Pro on fal) — better when composing
  **many references** (up to 14), when you need **web-search grounding** for factual
  content, **4K** output, a **seed** for reproducibility, or aspect-ratio-by-name control.
- **`nano-banana-image-editor`** — same model family through a direct Google key rather
  than fal billing.

## Prerequisites

A fal.ai API key. Set once:

```bash
export FAL_KEY=your_key_here
# or persist:
mkdir -p ~/.config/fal && echo your_key_here > ~/.config/fal/key
```

Get a key at https://fal.ai/dashboard/keys.

## Usage

Mode is implicit: **no `--image` means text-to-image, `--image` means edit.**

```bash
SKILL=${CLAUDE_PLUGIN_ROOT:-$HOME/.claude}/skills/gpt-image/scripts/generate.py

# Generate (flare, the default)
python3 $SKILL \
  --prompt "A serene minimalist illustration of a lighthouse at sunrise, warm cream palette" \
  --output ~/out.png
```

### Premium detail

```bash
python3 $SKILL --tier sunburst --quality xhigh \
  --prompt "Art-nouveau poster, intricate gold filigree border, letterpress texture" \
  --output ~/hero.png
```

### Edit an existing image

`--image` takes a **local path or a URL**. Local files upload to fal storage automatically.

```bash
python3 $SKILL \
  --image ~/photo.jpg \
  --prompt "Make it night-time, add neon signs in the background" \
  --output ~/out.png
```

### Edit with tightest control, across revision rounds

```bash
python3 $SKILL --tier sunburst \
  --image ~/poster.png \
  --prompt "Replace only the date line with '11-13 December 2026'. Leave everything else untouched." \
  --output ~/poster-v2.png
```

### Masked edit — confine changes to a region

```bash
python3 $SKILL --image ~/room.png --mask ~/room-mask.png \
  --prompt "Put a large window here" --output ~/room-window.png
```

### Transparent background (logos, stickers, overlays)

```bash
python3 $SKILL --background transparent --output-format png \
  --prompt "A flat vector capoeira berimbau icon, single colour, no background" \
  --output ~/icon.png
```

### 16:9 for presentation slides

```bash
python3 $SKILL --size 1792x1024 --quality high \
  --prompt "..." --output ~/slide.png
```

### Batch variations

```bash
python3 $SKILL --num-images 4 --prompt "..." --output ~/out.png
# saves ~/out-1.png … ~/out-4.png
```

### All flags

| Flag | Default | Notes |
|---|---|---|
| `--prompt` | required | Prompt, or the editing instruction |
| `--output` | required | Local path; parent dirs auto-created |
| `--tier` | `flare` | `flare` or `sunburst` |
| `--image` | — | Local path or URL. Repeatable, up to **16**. Presence switches to edit mode |
| `--mask` | — | Edit mode only; confines changes to a region |
| `--size` | `landscape_4_3` generating, `auto` editing | Preset, `auto`, or `WxH` |
| `--quality` | `high` | `auto`, `low`, `medium`, `high`, `xhigh`, `max` |
| `--background` | `auto` | `auto`, `transparent`, `opaque` |
| `--num-images` | `1` | **1–10**. >1 suffixes filenames `-1`, `-2`, … |

From sejas/ai-code-skills, MIT.

More from sejas/ai-code-skills