/generate-image

name: generate-image
description: Generate or edit images with AI models through the OpenRouter Image API (Gemini, Seedream, Recraft, GPT-Image, Riverflow). 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, inspecting a model, and --dry-run do not. Targets the OpenRouter Image API (POST /api/v1/images) as verified on 2026-07-31.
allowed-tools: Read Write Edit Bash
metadata:
  version: "3.1"
  skill-author: K-Dense Inc.
  last-reviewed: "2026-07-31"
  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, Seedream, Recraft, GPT-Image, Riverflow, 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, 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

# 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

Paths are relative to this skill's directory. Output defaults to `generated_image.<ext>`, where the extension follows the media type the model returned. The per-request cost is printed after the run.

**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, reproducible seeds | `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` — see the caveat below |

`references/models.md` carries the full catalogue with per-model parameters, allowed values, and prices. The live listing is authoritative and free:

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**, and sending something a model does not support is rejected, not ignored.

The script checks the request against the live catalogue before spending anything, so a bad parameter fails locally in under a second with the legal values printed:

$ python scripts/generate_image.py "abstract pattern" -m openai/gpt-image-2 --background transparent
Error: Request rejected before billing (1 problem):
  - background=transparent is not allowed; this model accepts: auto, opaque

Rough guide — but let the check be the authority, since the catalogue moves:

• `--resolution` — Gemini, Seedream, Riverflow, Krea, Grok. The tiers differ: `512` only on Gemini

3.1 Flash, `4K` on Gemini 3 Pro / Seedream / Riverflow, and **`1K` only** on `gemini-3.1-flash-lite-image` and the Krea models.

• `--output-format` — Riverflow 2.5 only (`png`, `jpeg`, `webp`; the `fast` variant takes `jpeg`

alone). Gemini, OpenAI, Seedream, and Recraft all choose their own container.

• `--quality`, `--background`, `--output-compression` — the OpenAI family, plus `--background` on

Riverflow 2.5. **`--background transparent` is not available on `gpt-image-2` or `gpt-5.4-image-2`** — use `gpt-image-1`, `gpt-image-1-mini`, `gpt-5-image`, or `gpt-5-image-mini`.

• `--seed` — Seedream and Krea. Not Gemini, not OpenAI.
• `--aspect-ratio` — nearly all models, but the enum differs sharply: `gpt-image-1` accepts only

`1:1`, `3:2`, `2:3`, `auto`, and `gpt-5-image*` does not accept it at all.

• `--n` — capped per model: 1 for Gemini, Riverflow, MAI and Grok, 6 for Recraft, 10 for Seedream

and OpenAI. The Krea models reject it outright.

Pass `--dry-run` to validate and print the exact request body without generating or billing. `--no-preflight` skips the check when you want the API itself to arbitrate.

Writing the prompt

Prompt quality decides output quality more than model choice does. Name, in one sentence each:

1. **Subject** — what is in frame, and how much of it. "A single