Generate Image

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.

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

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

# 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