v2.0 to v3.0

+ 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.

+ 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.

+ version: "3.0"

+ last-reviewed: "2026-07-31"

+ 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.

+ 3. `OPENROUTER_API_KEY=` in a `.env` file, searching the working directory upward, then the

+ script's own directory

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

+ 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.

+

+ | 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

+ 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:

+ ```console

+ $ 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 pipette tip above a 96-well plate."

+ 2. **Medium and style** — photograph, watercolour, 3D render, flat vector, scientific illustration.

+ 3. **Lighting and palette** — "soft diffuse lighting, cool blue and white palette."

+ 4. **Composition** — "wide shot, subject left of centre, empty space on the right for a title."

+ 5. **What to avoid** — "no text, no labels, no watermark."

+

+ Asking for empty space where a caption or title will go is the single most useful compositional

+ instruction for posters and slides.

+

+ Iterate cheaply: draft on `gemini-3.1-flash-lite-image`, then regenerate the wording you settled on

+ with the model you actually want. To refine rather than restart, feed the last output back as a

+ reference (`-i out.png`) and describe only the change.

+

+ Reference limits differ: 16 for OpenAI, 14 for Gemini and Seedream, 10 for `riverflow-v2*-pro`,

+ 3 for `gemini-2.5-flash-image` and Grok, 1 for Recraft, MAI, and Krea. Accepted local formats: PNG,

+ JPEG, GIF, WebP. Riverflow v2 bills $0.20 per reference image on top of the output.

+ The `-o` paths are destinations the script creates, not files bundled with the skill.

+

+ # Wide hero image for a poster, with space reserved for the title

+ "Laboratory with modern equipment, photorealistic, well-lit, wide shot, \

+ equipment on the left, empty wall on the right, no text" \

+ --aspect-ratio 21:9 --resolution 2K -o poster/hero.png

+ # Conceptual illustration for a manuscript — illustrative, never presented as data

+ "Stylised illustration of immune cells surrounding a tumour cell, scientific illustration, \

+ cool palette, no text" \

+ -m recraft/recraft-v4.1-vector -o assets/logo.svg

+ "Abstract molecular pattern, subtle, blue and white, no text" \

+ -m openai/gpt-image-1 --background transparent -o slides/bg.png

+ -m bytedance-seed/seedream-4.5 --seed 42

+

+ # Check a request costs nothing to get wrong

+ python scripts/generate_image.py "A cat astronaut" --resolution 4K --dry-run

+ | `prompt` | Image description, or the edit to apply (required unless `--list-models` / `--model-info`) |

+ | `--aspect-ratio` | `1:1`, `16:9`, `9:16`, `4:3`, `3:2`, `21:9`, … — enum differs per model |

+ | `--resolution` | `512`, `1K`, `2K`, `4K` — tiers differ per model |

+ | `--quality` | `auto`, `low`, `medium`, `high` (OpenAI) |

+ | `--output-format` | `png`, `jpeg`, `webp` (Riverflow 2.5) |

+ | `--output-compression` | 0–100, OpenAI models |

+ | `--retries` | Retries for rate limits and 5xx responses (default 2) |

+ | `--no-preflight` | Skip the free capability check before the billed request |

+ | `--dry-run` | Validate and print the request, then exit without generating |

+ | `--list-models` | Print the catalogue with allowed values, optionally filtered, then exit |

+ | `--model-info` | Print one model's allowed values and pricing, then exit |

+ There is no `--size`: no model in the catalogue accepts a `size` parameter. Shape output with

+ `--aspect-ratio` and `--resolution`.

+

+ "usage": {

+ "prompt_tokens": 4,

+ "completion_tokens": 1120,

+ "total_tokens": 1124,

+ "cost": 0.0672,

+ "completion_tokens_details": { "image_tokens": 1120 }

+ }

+ when naming files — vector models return `image/svg+xml`, and `gemini-3.1-flash-lite-image` returns

+ JPEG rather than PNG.

+ not billed — so a rejected parameter costs nothing but time. Streaming preview frames are not

+ charged separately. On a bring-your-own-key account `usage.cost` reads `0` and the real amount is

+ in `cost_details.upstream_inference_cost`; the script reports that figure rather than claiming the

+ run was free.

+ ## Cost

+

+ Per-image models are predictable: Seedream $0.04, Recraft v4.1 $0.035 (vector $0.08, pro $0.21),

+ Riverflow 2.5 fast $0.019 and pro $0.13–0.17, Grok $0.05–0.07.

+

+ Gemini, OpenAI, and MAI bill per output token, which scales with resolution — a 4K image costs

+ roughly sixteen times a 1K one. Measured: one 1K `gemini-3.1-flash-lite-image` render is 1120

+ output tokens, $0.034. At the same size `gemini-3.1-flash-image` is double that and

+ `gemini-3-pro-image` four times. Draft at low resolution on a cheap model; pay for size once.

+

+ - **Models cannot be trusted with text.** Words inside a generated image come back misspelled,

+ garbled, or invented. Ask for "no text" and overlay real type in LaTeX, PowerPoint, or HTML — or

+ use `scientific-schematics` when labels are the point.

+ - **A generated image is an illustration, never evidence.** It shows nothing that was measured.

+ Never present one as microscopy, imaging, gel, or instrument output, never let it stand in for a

+ figure that reports results, and label it as an illustration in captions. Nature and Science both

+ require disclosure of generative-AI imagery, and several journals prohibit it outside

+ clearly-marked concept art — check the target venue before submitting.

+ - Generation is a paid API call. Prefer a cheap model and low resolution while iterating on wording.

+ - Reference images are uploaded to OpenRouter. Do not send unpublished or sensitive data, patient

+ images, or anything under embargo.

+ - A refusal arrives as an HTTP 400 or 403 mentioning content policy, not as a bad image. Rephrase —

+ clinical and anatomical subjects trip moderation more often than the request warrants.

+ - Rate limits and 5xx responses are retried automatically; a 4xx is final, because the request

+ itself is what needs changing.