/generate-image

name: generate-image
description: Generate or edit images with AI models through the OpenRouter Image API (Gemini, FLUX, Seedream, Recraft, GPT-Image). 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. The bundled script uses only the standard library. Image generation requires the OPENROUTER_API_KEY credential and bills per request; listing models does not. Targets the OpenRouter Image API (POST /api/v1/images) as documented on 2026-07-26.
allowed-tools: Read Write Edit Bash
metadata:
  version: "2.0"
  skill-author: K-Dense Inc.
  last-reviewed: "2026-07-26"
  openclaw:
    primaryEnv: OPENROUTER_API_KEY
    envVars:
      - name: OPENROUTER_API_KEY
        required: true
        description: OpenRouter API key used for image generation.

Generate Image

Generate and edit images through OpenRouter's Image API, which reaches Gemini, FLUX, Seedream, Recraft, GPT-Image, and roughly thirty other models behind one request shape.

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

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

`--list-models` needs no key.

Quick start

# 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

Output defaults to `generated_image.<ext>`, where the extension follows the media type the model returned. The per-request cost is printed from `usage.cost`.

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` | | Photoreal control, reproducible seeds | `black-forest-labs/flux.2-pro` | | Cheap iteration | `black-forest-labs/flux.2-klein-4b` | | Several images per request | `bytedance-seed/seedream-4.5`, `openai/gpt-image-2` | | Vector / SVG output | `recraft/recraft-v4-vector` | | Transparent background | `openai/gpt-image-2` with `--background transparent` |

`references/models.md` carries the full catalogue with per-model parameter support. The live listing is authoritative:

python scripts/generate_image.py --list-models

Parameter support varies by model

This is the main thing to get right. Models advertise different parameter sets, and **sending a parameter a model does not support is rejected, not ignored**. The script omits every flag you do not pass, so pass only what the target model accepts.

• `--resolution` (`512`, `1K`, `2K`, `4K`) — Gemini, Seedream, Riverflow, Krea, Grok. **Not FLUX.**
• `--output-format` — FLUX and Riverflow 2.5. **Not Gemini.**
• `--quality`, `--background`, `--output-compression` — the OpenAI family.
• `--seed` — FLUX, Seedream, Krea. **Not Gemini, not OpenAI.**
• `--aspect-ratio` — nearly all models, but the allowed enum differs.
• `--n` — capped per model: 1 for Gemini and FLUX, 6 for Recraft, 10 for Seedream and OpenAI.

On an HTTP 400 the script prints OpenRouter's message and points at `--list-models`.

Editing and reference images

`-i/--input` is repeatable and accepts local paths, HTTP(S) URLs, or data URLs. Local files are base64-encoded and sent as `input_references`.

# Single-image edit
python scripts/generate_image.py "Add sunglasses to the person" -i portrait.png

# Composite several references
python scripts/generate_image.py "Blend these two styles" -i style_a.png -i style_b.jpg -o blend.png

# Reference an image already on the web
python scripts/generate_image.py "Restyle as a watercolor" -i https://example.com/photo.jpg

Reference limits differ: 16 for OpenAI, 14 for Gemini and Seedream, 8 for FLUX, 1 for Recraft and MAI. Accepted local formats: PNG, JPEG, GIF, WebP.

Worked examples

# Wide hero image for a poster
python scripts/generate_image.py \
  "Laboratory with modern equipment, photorealistic, well-lit" \
  -m black-forest-labs/flux.2-pro --aspect-ratio 21:9 -o poster/hero.png

# Conceptual figure for a manuscript
python scripts/generate_image.py \
  "Microscopic view of cancer cells attacked by immunotherapy agents, scientific illustration" \
  --resolution 2K -o figures/immunotherapy_concept.png

# Vector logo
python scripts/generate_image.py \
  "Minimal geometric fox logo, two colors" \
  -m recraft/recraft-v4-vector -o assets/logo.svg

# Slide background with a transparent alpha channel
python scripts/generate_image.py \
  "Abstract molecular pattern, subtle, blue and white" \
  -m openai/gpt-image-2 --background transparent -o slides/bg.png

# Four variations in one request
python scripts/generate_image.py \
  "Stylized neuron network illustration" \
  -m bytedance-seed/seedream-4.5 --n 4 -o variations.png
# -> variations_1.png ... variations_4.png

# Reproducible output
python scripts/generate_image.py "A cat astronaut" \
  -m black-forest-labs/flux.2-pro --seed 42

Script parameters

| Flag | Purpose | | --- | --- | | `prompt` | Image description, or the edit to apply (required unless `--list-models`) | | `-m`, `--model` | Model slug (def