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

# 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

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

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:

```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**, 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.

## 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`.

```bash
# 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, 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.

## Worked examples

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

```bash
# Wide hero image for a poster, with space reserved for the title
python scripts/generate_image.py \
  "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
python scripts/generate_image.py \
  "Stylised illustration of immune cells surrounding a tumour cell, scientific illustration, \
   cool palette, no text" \
  --resolution 2K -o figures/immunotherapy_concept.png

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

# Slide background with a transparent alpha channel
python scripts/generate_image.py \
  "Abstract molecular pattern, subtle, blue and white, no text" \
  -m openai/gpt-image-1 --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 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
```

## Script parameters

| Flag | Purpose |
| --- | --- |
| `prompt` | Image description, or the edit to apply (required unless `--list-models` / `--model-info`) |
| `-m`, `--model` | Model slug (default `google/gemini-3.1-flash-image`) |
| `-o`, `--output` | Output path; extension defaults to the returned media type |
| `-i`, `--input` | Reference image — path, URL, or data URL. Repeatable |
| `--n` | Images per request, model-capped |
| `--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) |
| `--background` | `auto`, `transparent`, `opaque` |
| `--output-compression` | 0–100, OpenAI models |
| `--seed` | Deterministic output where supported |
| `--api-key` | Overrides the environment and `.env` |
| `--timeout` | Request timeout, seconds (default 300) |
| `--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`.

## API shape

For direct requests without the script:

```bash
curl -s https://openrouter.ai/api/v1/images \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-3.1-flash-image",
    "prompt": "A red bicycle against a white wall",
    "aspect_ratio": "16:9"
  }'
```

Response:

```json
{
  "created": 1748372400,
  "data": [{ "b64_json": "<base64>", "media_type": "image/png" }],
  "usage": {
    "prompt_tokens": 4,
    "completion_tokens": 1120,
    "total_tokens": 1124,
    "cost": 0.0672,
    "completion_tokens_details": { "image_tokens": 1120 }
  }
}
```

`b64_json` is raw base64, **not** a data URL. `media_type` reflects the real format, so honour it
when naming files — vector models return `image/svg+xml`, and `gemini-3.1-flash-lite-image` returns
JPEG rather than PNG.

Streaming (`"stream": true`) emits `image_generation.partial_image`, `image_generation.completed`,
and `error` events, terminating with `data: [DONE]`. Only the OpenAI models support it, and the
bundled script does not use it.

Billing is all-or-nothing: a generation is either completed and billed in full, or it fails and is
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.

## Notes and caveats

- **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.
- Generation takes roughly 5–60 seconds depending on model and resolution.
- Reference images are uploaded to OpenRouter. Do not send unpublished or sensitive data, patient
  images, or anything under embargo.
- Never hardcode the API key. Keep it in the environment or an ignored `.env`.
- Prompt specifically when editing: "change the sky to sunset colours" beats "edit the sky".
- 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.

## Related skills

- `scientific-schematics` — technical diagrams, flowcharts, circuits, pathways
- `scientific-slides` — presentations that embed generated visuals
- `latex-posters` — posters that embed hero images