Openrouter Image Generate

OpenRouter Image Generation

Use this skill to generate images with OpenRouter's dedicated Image API and save the returned base64 image bytes to files.

Default workflow

1. Use the OpenRouter API key from the current environment first. If it is missing, rely on the bundled script's automatic lookup of the nearest project .env file containing OPENROUTER_API_KEY, unless the user explicitly provides another environment variable name or env file path.
2. Pick a model from the user's request. If no model is specified, use bytedance-seed/seedream-4.5 as a practical default and mention that the user can override it.
3. Use the bundled script at scripts/openrouter_image_generate.py rather than constructing requests manually.
4. Save generated images to a user-visible output directory, defaulting to the current working directory if the user did not specify one.
5. When the user or agent requires transparency, prefer a model/endpoint that supports native transparent output and pass --background transparent without --remove-background.
6. Use --remove-background only when the user or agent requires transparency and the selected model/endpoint does not support native transparent backgrounds. Follow the transparent-background workflow below; the flag assumes a chroma-key prompt and always processes final PNG/WebP outputs locally.
7. Do not print API keys. Do not put API keys directly on the command line because shell history may capture them.

Bundled script

Run from this skill directory or pass the script path directly:

python scripts/openrouter_image_generate.py generate \
  --prompt "a red panda astronaut floating in space, studio lighting" \
  --model "bytedance-seed/seedream-4.5" \
  --resolution 2K \
  --aspect-ratio 16:9 \
  --output-dir ./outputs

The script reads OPENROUTER_API_KEY from the current environment first. If it is not set, it automatically searches from the current working directory upward for the nearest .env file and reads OPENROUTER_API_KEY=... from there. Use --api-key-env MY_OPENROUTER_KEY if the key uses a different variable name, or --env-file ./path/to/.env to force a specific env file.

Common generation options

Pass only the options the user asks for or that are clearly needed:

• --prompt TEXT is required for generation.
• --model MODEL_ID defaults to bytedance-seed/seedream-4.5.
• --n 1..10 requests multiple images when supported by the endpoint.
• --resolution 512|1K|2K|4K sets the normalized resolution tier.
• --aspect-ratio 1:1|16:9|9:16|4:3|3:4|... sets the normalized ratio.
• --size 2048x2048 or --size 2K is the shorthand alternative. Do not combine explicit pixel sizes with mismatched --resolution or --aspect-ratio.
• --quality auto|low|medium|high controls provider quality where supported.
• --output-format png|jpeg|webp|svg controls the saved file type when supported.
• --background auto|transparent|opaque sets background where supported.
• --remove-background always runs the bundled chroma-key remover on final PNG/WebP outputs. It is a local option and is not sent to OpenRouter.
• --output-compression 0..100 applies to jpeg/webp where supported.
• --seed INTEGER requests deterministic generation where supported.
• --reference PATH_OR_URL can be passed multiple times for image-to-image/reference inputs. Local files are converted to data URLs.
• --provider-options-json '{"black-forest-labs":{"steps":40,"guidance":3}}' passes provider-specific options under provider.options.
• --provider-options-file options.json is safer for larger provider options.
• --raw-json payload.json can merge additional OpenRouter-compatible request fields into the payload.
• --dry-run prints the request payload without making a network call.

Model discovery

List available image models:

python scripts/openrouter_image_generate.py models

Show endpoint/provider capabilities for one model:

python scripts/openrouter_image_generate.py endpoints --model bytedance-seed/seedream-4.5

Use discovery before passing unusual parameters. OpenRouter image models differ by provider, and unsupported parameters may be ignored or rejected.

Output behavior

The script writes a single generated image as <output-prefix>.<ext> and multiple generated images as <output-prefix>_001.<ext>, <output-prefix>_002.<ext>, and so on. SVG outputs are decoded as text bytes and saved with .svg; raster outputs are decoded from base64 and saved with the requested or returned media type.

The script also writes a JSON metadata file by default with the request payload minus secrets, OpenRouter usage, created timestamp, and generated file paths. Use --no-metadata to skip it.

When --remove-background is present, every final PNG/WebP output is processed with the bundled scripts/remove_chroma_key.py copy, regardless of its existing alpha values. JPEG, SVG, and streaming partial previews are never processed. If Pillow is unavailable or the remover cannot run successfully, print a warning and return the original generated image normally. Without the flag, do not run local background removal.

Streaming

Use --stream only when the selected endpoint supports streaming. The script saves completed images from streaming responses and can optionally save partial previews with --save-partials.

Safety and cost

Image generation can bill the user's OpenRouter account. Before running a real generation command, make sure the requested model, image count, and output options match the user's intent. Use --dry-run when uncertain.

Transparent-background workflow

OpenRouter includes models that can produce true transparency. When the user or agent requires a transparent background, first check the selected model/endpoint with endpoints if its capability is unclear. If it supports native transparent output, prefer --background transparent --output-format png (or WebP) and do not pass --remove-background.

Use the chroma-key fallback only when both conditions are true: the user or agent requires a transparent result, and the selected model/endpoint does not support native transparency. Do not use --remove-background merely because support is unknown; inspect the endpoint or choose a transparency-capable model first.

Fallback sequence:

1. Choose a key color unlikely to appear in the subject: default #00ff00, use #ff00ff for green subjects, and avoid #0000ff for blue subjects.
2. Append only the following execution constraints to the supplied prompt, replacing the key color when needed:

Create the requested subject on a perfectly flat solid #00ff00 chroma-key background for background removal.
The background must be one uniform color with no shadows, gradients, texture, reflections, floor plane, or lighting variation.
Keep the subject fully separated from the background with crisp edges and generous padding.
Do not use #00ff00 anywhere in the subject.
No cast shadow, no contact shadow, no reflection, no watermark, and no text unless explicitly requested.

3. Generate a PNG with --background opaque --output-format png --remove-background. The flag does not modify the prompt or decide whether chroma-key removal is appropriate; it only applies the bundled post-processor to every final PNG/WebP output after generation.
4. The flag invokes the bundled helper with the workflow's calibrated defaults, equivalent to:

python scripts/remove_chroma_key.py \
  --input generated.png \
  --out transparent.png \
  --auto-key border \
  --soft-matte \
  --transparent-threshold 12 \
  --opaque-threshold 220 \
  --despill

Use the helper directly only when post-processing an image that already exists. For a new generation, prefer --remove-background so generation and post-processing share one command. The flag requires Pillow and a final .png or .webp output; it preserves the original generated image if post-processing fails.

5. Verify that an alpha channel exists, the corners are transparent, subject coverage is plausible, interior detail remains intact, and no obvious key-color fringe is present.
6. If a thin fringe remains, retry the helper once with --edge-contract 1. Use --edge-feather 0.25 only when the edge is visibly stair-stepped and the subject is not shiny or reflective.

Write the final output as .png or .webp to preserve alpha. If the matte removes subject details or the subject contains the key color, regenerate with a contrasting key color instead of increasing tolerance aggressively.

Chroma-key removal is unsuitable for hair, fur, feathers, smoke, glass, liquids, translucent materials, reflective objects, soft shadows, realistic product grounding, or subjects that conflict with every practical key color. If the fallback fails validation or the subject is unsuitable, report the limitation instead of presenting the result as valid transparency.

remove_chroma_key.py options

40x troubleshooting notes

These are real failure modes observed while testing OpenRouter image generation:

• 400 with n: must be exactly 1 means the model advertises or accepts an n parameter but that endpoint/provider only allows one image per request. Retry with --n 1, or choose a model whose supported_parameters.n.max is greater than 1.
• 400 with Streaming is not supported with n > 1 means OpenRouter/OpenAI streaming can only be used for a single image. For multiple images, remove --stream or generate one image per streaming request.
• 400 with provider-specific size or resolution messages means the normalized options still need to satisfy the upstream provider's constraints. For example, Seedream 4.5 rejected 1K square output because the image size was below its minimum pixel count; increasing to --resolution 2K fixed the request.
• 429 from an upstream provider means the provider is rate-limiting or temporarily capacity-limited. This is not a script bug; retry later, use a lower-cost/lower-demand model, or switch providers.
• A model may accept --n 2 but still return only one image. Trust the response length when naming files and metadata; if the user specifically needs multiple outputs, choose a model that has been observed returning multiple images, such as recraft/recraft-v4.1-pro.