domains / media / ai-image-generation / generate-image

generate-image

Skill card

combined

Both copies describe the same OpenRouter-based image generation skill, but they disagree on the model catalog, default model, and parameter surface. The K-Dense copy is a newer, more detailed revision (v3.3) that lists Gemini 3.1 Flash, Seedream, Recraft, GPT-Image, and Riverflow, and includes detailed parameter validation, resolution/quality/background constraints, and a 'look at the image' verification step. The Vibe-Skills copy is an older revision that lists FLUX.2 Pro/Flex and Gemini 3.1 Flash Image Preview, and includes a more explicit manual API key setup procedure and example use cases for scientific documents. Because the model lists and defaults conflict, crowning one would hide the alternative model set and the specific setup steps present only in the other.

Repositories

Other copies

Combined skill

---
name: generate-image
description: Generates or edits images with AI models through the OpenRouter Image API. Use for photos, illustrations, artwork, concept art, visual assets, logos, and image editing or compositing from reference images. For flowcharts, circuits, pathways, and other technical diagrams, use the scientific-schematics skill instead.
license: MIT
compatibility: Requires Python 3.9+ and network access to openrouter.ai. Image generation requires the OPENROUTER_API_KEY credential.
allowed-tools: Read Write Edit Bash
metadata:
  version: "3.3"
  skill-author: K-Dense Inc.
---

# Generate Image

Generate and edit images through OpenRouter's Image API.

## When to use

**Use this skill for:** photos and photorealistic images, illustrations and artwork, concept art, presentation and poster visuals, logos and vector marks, image editing, and compositing from reference images.

**Use `scientific-schematics` instead for:** flowcharts, circuit diagrams, biological pathways, system architecture diagrams, CONSORT diagrams, and other technical schematics.

## API key

Generation requires an OpenRouter key. The script resolves it in this order:

1. `--api-key`
2. the `OPENROUTER_API_KEY` environment variable
3. `OPENROUTER_API_KEY=` in a `.env` file, searching the working directory upward, then the script's own directory

If none is present the script exits with setup instructions. Keys: https://openrouter.ai/keys

`--list-models`, `--model-info`, and `--dry-run` need no key.

## Quick start

```bash
# Generate
python scripts/generate_image.py "A beautiful sunset over mountains"

# Edit an existing image
python scripts/generate_image.py "Make the sky purple" -i photo.jpg -o edited.png
```

Run these commands from the skill directory; input and output paths resolve from the working directory. Output defaults to `generated_image.<ext>`, using each image's returned media type (or `.bin` when unknown). An explicit output suffix is kept, with a warning on mismatch; the script does not transcode. OpenRouter and upstream costs are printed separately when supplied.

**Then look at the image.** Read the file back and check it before using it anywhere: composition, aspect ratio, and any text are all things models get wrong silently.

## Choosing a model

Default: `google/gemini-3.1-flash-image`.

| Need | Model |
| --- | --- |
| General quality, prompt adherence | `google/gemini-3.1-flash-image` |
| Highest Gemini tier | `google/gemini-3-pro-image` |
| Cheap iteration | `google/gemini-3.1-flash-lite-image` (1K only), `openai/gpt-image-1-mini` |
| Photoreal control, seeded generation | `bytedance-seed/seedream-4.5` |
| Several images per request | `bytedance-seed/seedream-4.5`, `openai/gpt-image-2` (up to 10) |
| Vector / SVG output | `recraft/recraft-v4.1-vector` |
| Transparent background | `openai/gpt-image-1` with `--background transparent` |
| Legible text inside the image | `recraft/recraft-v4.1`, `sourceful/riverflow-v2.5-pro` |

[references/models.md](references/models.md) carries the reviewed capability and pricing snapshot. The live listing is authoritative and free:

```bash
python scripts/generate_image.py --list-models            # every model and its allowed values
python scripts/generate_image.py --list-models gemini     # filtered by substring
python scripts/generate_image.py --model-info openai/gpt-image-1   # one model, plus pricing
```

## Parameter support varies by model

This is the main thing to get right. Models advertise different parameter sets **and different allowed values**. The CLI conservatively rejects unadvertised options; individual providers may ignore or normalize some fields. The generic guide can lag the discovery records.

The script checks the model catalogue and requires at least one provider endpoint to accept the complete combination before generation. Model capabilities are a union across endpoints, not a promise that every provider supports them. Unsupported requests fail locally with legal values.

Current examples of capability differences (reviewed 2026-09-30):

- `--resolution`: Gemini 3.1 Flash accepts `512`, `1K`, `2K`, `4K`; Flash Lite and Krea accept only `1K`. Seedream 5.0 Lite accepts `2K`/`4K`, while 5.0 Pro accepts `1K`/`2K`.
- `--output-format`: Riverflow 2.5 Pro accepts `png`/`jpeg`/`webp`; its Fast variant accepts only `jpeg`. Recraft vector models accept `svg`. OpenAI models do not advertise this flag.
- `--quality`: GPT Image 2.5 Flare/Sunburst also accept `xhigh`/`max`; Grok 2.0 accepts only `low`/`medium`. Inspect the specific model before selecting a quality value.
- `--background transparent` is **not available** on `gpt-image-2` or `gpt-5.4-image-2`. It is advertised on GPT Image 1 and 2.5. Do not combine transparency with JPEG; when no output format is selectable, inspect the returned file for an actual alpha channel.
- `--aspect-ratio`: GPT-5 Image and Mini now accept `1:1`, `3:2`, `2:3`, `auto`; GPT-5.4 Image 2 also accepts wider ratios. None accept a resolution flag in this snapshot.
- `--n` is an upper bound, not a guarantee: providers may return fewer images.

## Common Usage Patterns

### Basic generation
```bash
python scripts/generate_image.py "Your prompt here"
```

### Specify model
```bash
python scripts/generate_image.py "A cat in space" --model "google/gemini-3.1-flash-image"
```

### Custom output path
```bash
python scripts/generate_image.py "Abstract art" --output artwork.png
```

### Edit an existing image
```bash
python scripts/generate_image.py "Make the background blue" --input photo.jpg
```

### Edit with a specific model
```bash
python scripts/generate_image.py "Add sunglasses to the person" --input portrait.png --model "google/gemini-3.1-flash-image"
```

### Edit with custom output
```bash
python scripts/generate_image.py "Remove the text from the image" --input screenshot.png --output cleaned.png
```

### Multiple images
Run the script multiple times with different prompts or output paths:
```bash
python scripts/generate_image.py "Image 1 description" --output image1.png
python scripts/generate_image.py "Image 2 description" --output image2.png
```

## Script Parameters

- `prompt` (required): Text description of the image to generate, or editing instructions
- `--input` or `-i`: Input image path for editing (enables edit mode)
- `--model` or `-m`: OpenRouter model ID (default: google/gemini-3.1-flash-image)
- `--output` or `-o`: Output file path (default: generated_image.png)
- `--api-key`: OpenRouter API key (overrides .env file)

## Example Use Cases

### For Scientific Documents
```bash
# Generate a conceptual illustration for a paper
python scripts/generate_image.py "Microscopic view of cancer cells being attacked by immunotherapy agents, scientific illustration style" --output figures/immunotherapy_concept.png

# Create a visual for a presentation
python scripts/generate_image.py "DNA double helix structure with highlighted mutation site, modern scientific visualization" --output slides/dna_mutation.png
```

### For Presentations and Posters
```bash
# Title slide background
python scripts/generate_image.py "Abstract blue and white background with subtle molecular patterns, professional presentation style" --output slides/background.png

# Poster hero image
python scripts/generate_image.py "Laboratory setting with modern equipment, photorealistic, well-lit" --output poster/hero.png
```

### For General Visual Content
```bash
# Website or documentation images
python scripts/generate_image.py "Professional team collaboration around a digital whiteboard, modern office" --output docs/team_collaboration.png

# Marketing materials
python scripts/generate_image.py "Futuristic AI brain concept with glowing neural networks" --output marketing/ai_concept.png
```

## Error Handling

The script provides clear error messages for:
- Missing API key (with setup instructions)
- API errors (with status codes)
- Unexpected response formats
- Missing dependencies (requests library)

If the script fails, read the error message and address the issue before retrying.

## Notes

- Images are returned as base64-encoded data URLs and automatically saved as PNG files
- The script supports both generation and editing modes

## Conflicts

- **K-Dense-AI/scientific-agent-skills::skills/generate-image/SKILL.md** sets the default model to `google/gemini-3.1-flash-image`, while **foryourhealth111-pixel/Vibe-Skills::bundled/skills/generate-image/SKILL.md** sets it to `google/gemini-3.1-flash-image-preview`.
- **K-Dense-AI/scientific-agent-skills::skills/generate-image/SKILL.md** lists Seedream, Recraft, GPT-Image, and Riverflow as available models, while **foryourhealth111-pixel/Vibe-Skills::bundled/skills/generate-image/SKILL.md** lists FLUX.2 Pro and FLUX.2 Flex instead.
- **K-Dense-AI/scientific-agent-skills::skills/generate-image/SKILL.md** includes detailed parameter validation and model-specific capability constraints, while **foryourhealth111-pixel/Vibe-Skills::bundled/skills/generate-image/SKILL.md** does not.
- **K-Dense-AI/scientific-agent-skills::skills/generate-image/SKILL.md** instructs the agent to read the file back and check the image after generation, while **foryourhealth111-pixel/Vibe-Skills::bundled/skills/generate-image/SKILL.md** does not.
- **foryourhealth111-pixel/Vibe-Skills::bundled/skills/generate-image/SKILL.md** includes a manual API key setup procedure that is not present in the K-Dense copy.