OpenRouter image generator

This small Python CLI uses requests and OpenRouter's dedicated Image API. It sends one request per iteration. By default, the first image generated by an iteration is added as a reference image for the next iteration.

Install

cd /home/gordon/workspace/openrouter-image-generator
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements.txt
export OPENROUTER_API_KEY='your-key'

Generate images

python openrouter_images.py \
  --model openai/gpt-image-1 \
  --prompt 'A small cabin beside a forest lake at sunrise' \
  --count 3 \
  --output-dir ./work \
  --quality high \
  --background opaque \
  --resolution 1K \
  --aspect-ratio 16:9

The program saves images and manifest.jsonl in the output directory. The count is intentionally implemented as sequential requests, rather than one request with n, so that iteration 2 can use iteration 1 as a reference.

Use existing local or remote references with one or more --reference options:

python openrouter_images.py \
  --model openai/gpt-image-1 \
  --prompt 'Turn this into a watercolor illustration' \
  --reference ./source.png \
  --count 4 \
  --output-dir ./work

Local image paths are converted to base64 data URLs. http://, https://, and data: references are passed through unchanged. Use --no-chain when each iteration should use only the explicitly supplied references.

Optional fields are omitted unless supplied. Before generation, the CLI checks the model's reported capabilities. This catches unsupported values for fields such as quality, background, resolution, aspect_ratio, and reference images. Use --skip-capability-check only when you want to bypass that check.

Inspect model functionality

Print model-level capabilities and definitive per-provider capabilities:

python openrouter_images.py --model-info openai/gpt-image-1

Print the raw model record as JSON:

python openrouter_images.py --model-info openai/gpt-image-1 --json

List available image models:

python openrouter_images.py --list-models

The model-level list is a union across providers. The per-provider section is the more precise source when providers expose different parameters.

Main options

--model MODEL                 OpenRouter image model ID
--prompt PROMPT               Prompt for each iteration
--count N                     Sequential iterations (default: 1)
--output-dir DIRECTORY        Image and manifest destination
--reference PATH_OR_URL       Repeat for reference images
--background auto|transparent|opaque
--quality auto|low|medium|high
--resolution 512|1K|2K|4K
--size TIER or WIDTHxHEIGHT
--aspect-ratio RATIO
--output-format png|jpeg|webp|svg
--chain / --no-chain          Reuse the previous output (default: --chain)
--model-info MODEL            Print model functionality and exit

Run python openrouter_images.py --help for all options.

Tests

python -m unittest discover -s tests -v