OpenRouter Image Generation & Editing

Generate new images or edit existing ones using OpenRouter image-capable models via the Chat Completions API.

Usage

Run the script using absolute path (do NOT cd to the skill directory first):

Generate new image:

# Ensure outbound directory exists first
mkdir -p ~/.openclaw/media/outbound

uv run ~/.openclaw/workspace/skills/openrouter-image-generation/scripts/generate_image.py \
  --prompt "your image description" \
  --filename "~/.openclaw/media/outbound/output-name.png" \
  --model google/gemini-2.5-flash-image \
  [--aspect-ratio 16:9] \
  [--image-size 2K]

Edit existing image (image-to-image):

# Ensure outbound directory exists first
mkdir -p ~/.openclaw/media/outbound

uv run ~/.openclaw/workspace/skills/openrouter-image-generation/scripts/generate_image.py \
  --prompt "editing instructions" \
  --filename "~/.openclaw/media/outbound/output-name.png" \
  --input-image "path/to/input.png" \
  --model google/gemini-2.5-flash-image

Important: Default OpenClaw delivery path is ~/.openclaw/media/outbound/. Save generated images there so other OpenClaw flows can pick them up easily.

API Key

The script checks for API key in this order:

1. --api-key argument
2. OPENROUTER_API_KEY environment variable

Optional OpenRouter attribution headers:

• --site-url or OPENROUTER_SITE_URL
• --app-name or OPENROUTER_APP_NAME

Model + Image Config

• --model <openrouter-model-id> is required (no script default)
• Example model: google/gemini-2.5-flash-image
• Use --aspect-ratio for image_config.aspect_ratio (for example 1:1, 16:9)
• Use --image-size for image_config.image_size (1K, 2K, 4K)
• Use --image-config-json '{"key":"value"}' for advanced/provider-specific extras (merged into image_config)

Note: OpenRouter docs show aspect_ratio and image_size as the common image config fields for image generation. Additional keys may exist for specific providers/models (for example Sourceful features). If a request fails, remove unsupported options or switch models.

Note: The script always sends modalities: ["image", "text"]. Image-only models (some FLUX variants) may reject this — if you get an unexpected error with a non-Gemini model, this may be the cause. No workaround is currently exposed via CLI args.

Default Workflow (draft -> iterate -> final)

Goal: iterate quickly before spending time on higher-quality settings.

• Draft: smaller size / faster model
  • --image-size 1K
• Iterate: adjust prompt in small diffs and keep a new filename each run
• Final: larger size or higher quality if the selected model supports it
  • Example: --image-size 4K --aspect-ratio 16:9

Preflight + Common Failures

• Preflight:
  • command -v uv
  • test -n "$OPENROUTER_API_KEY" (or pass --api-key)
  • test -d ~/.openclaw/media/outbound || mkdir -p ~/.openclaw/media/outbound
  • If editing: test -f "path/to/input.png"