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
python scripts/generate_image.py "A cat astronaut" --resolution 4K --dry-run

Script parameters

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:

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