generate-image

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.

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

API shape

For direct requests without the script:

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:

{
  "created": 1748372400,
  "data": [{ "b64_json": "<base64>", "media_type": "image/png" }],
  "usage": { "prompt_tokens": 0, "completion_tokens": 4175, "total_tokens": 4175, "cost": 0.04 }
}

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.

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. Streaming preview frames are not charged separately.

Notes and caveats

• Generation is a paid API call. Prefer a cheap model while iterating on a prompt.
• Generation takes roughly 5–60 seconds depending on model and resolution.
• Reference images are uploaded to OpenRouter. Do not send unpublished or sensitive data.
• 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".

Related skills

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