openrouter-icu-image
Generate or edit images synchronously through OpenRouter ICU's OpenAI-compatible image API. Use when the user asks Codex to create an image, produce visual assets, transform or edit local/reference im
SKILL.mdopenrouter-icu-image/SKILL.md
GitHubOpenRouter ICU Image
Core Workflow
- Check
OPENROUTER_ICU_API_KEYbefore making network requests. The CLI also loadsOPENROUTER_ICU_API_KEY=...from a private.envfile in the skill directory. If the key is still missing, ask the user for it and do not call the API. - Keep API controls out of the image prompt. The prompt should describe only the visual goal: subject, scene, composition, materials, lighting, style, and explicit visual constraints.
- Choose the endpoint:
- Text-to-image:
/v1/images/generations. - Local image editing or multi-image references:
/v1/images/edits.
- Text-to-image:
- Set explicit request parameters. Defaults are
model=gpt-image-2,size=1024x1024,quality=medium,output_format=png,stream=true, andpartial_images=2. - Run image generation synchronously. Do not background the command, detach the process, start a separate hidden terminal, or use fire-and-forget automation.
- Wait until the CLI process exits and the final image file is written before continuing with dependent work or sending a final response. If a terminal tool returns a live session ID, poll that session until it exits; do not start unrelated work while image generation is still running.
- Save outputs under a user-requested path when provided; otherwise use a clear local output path such as
output/openrouter-icu/<slug>.png. - After generation, verify the file exists and render or show it when useful.
Preferred CLI
Use scripts/openrouter_icu_image.py for most tasks. It uses only the Python 3 standard library, handles streaming SSE, validates core parameters, avoids accidental requests without an API key, and writes decoded images only after image payload fields are present.
For a local global install, keep a private file at C:\Users\Administrator\.codex\skills\openrouter-icu-image\.env with OPENROUTER_ICU_API_KEY=.... Do not put real keys in repo-local files, docs, examples, or chat.
On Windows, scripts\set_openrouter_icu_key.ps1 can prompt for the key and write the private .env file without echoing the value.
The CLI is synchronous by default: it does not exit until the HTTP response has completed, SSE events have been parsed, and final image files have been decoded and written. Treat a nonzero exit code as a failed generation and do not claim success.
Run the script from the skill directory or pass the script path appropriate for the installed location. Use a Python 3 launcher:
- macOS/Linux:
python3 scripts/openrouter_icu_image.py - Windows PowerShell/CMD:
python scripts\openrouter_icu_image.pywhenpythonpoints to Python 3 - Windows with the Python launcher:
py -3 scripts\openrouter_icu_image.py
Examples:
python3 scripts/openrouter_icu_image.py generate \
--prompt "A clean product photo of a white ceramic coffee mug on a wooden desk, soft natural light" \
--output output/openrouter-icu/mug.png
Windows equivalent:
python scripts\openrouter_icu_image.py generate `
--prompt "A clean product photo of a white ceramic coffee mug on a wooden desk, soft natural light" `
--output output\openrouter-icu\mug.png
python3 scripts/openrouter_icu_image.py edit \
--image input.png \
--prompt "Change the background to a clean modern office while preserving the subject, clothing, pose, and facial features" \
--output output/openrouter-icu/office.png
python3 scripts/openrouter_icu_image.py edit \
--image product.png \
--image background-reference.png \
--prompt "Create a premium product photo using the product from the first image and the environment style from the second image" \
--size 1536x1024 \
--quality high \
--output output/openrouter-icu/product.png
Use --dry-run to inspect the request shape without contacting the API.
CLI flags use hyphenated names while the API payload uses snake_case. The script also accepts the snake_case aliases for API-shaped options:
| CLI flag | API payload field |
|---|---|
--output-format / --output_format |
output_format |
--output-compression / --output_compression |
output_compression |
--stream, --stream true, --stream false |
stream |
--no-stream / --no_stream |
stream=false |
--partial-images / --partial_images |
partial_images |
--image / --image-file |
multipart image[] |
--file-id / --file_id |
images[].file_id |
--image-url / --image_url |
images[].image_url |
--base-url / --base_url |
request base; accepts https://openrouter.icu or https://openrouter.icu/v1 |
Parameter Rules
- Always set
size,quality, andoutput_formatexplicitly. - Use
quality=mediumunless the user specifies otherwise. - Use
output_format=pngunless the user asks forjpegorwebp. - Use
stream=trueandpartial_images=2by default for visible progress and robust final-event handling. - When using
--stream false,--no-stream, or--no_stream, omitpartial_imagesfrom the API payload. - For custom sizes, require
WIDTHxHEIGHT, dimensions divisible by 16, aspect ratio between1:3and3:1, and no more pixels than3840x2160. - Avoid sizes above
2560x1440unless the user needs high-resolution output.
Error Handling
400: print full error JSON, fix parameters, and do not retry unchanged.401: checkOPENROUTER_ICU_API_KEY; if absent or invalid, ask the user for a valid key.403/404: print full error JSON and check model, file IDs, image URLs, and permissions.408/409/429/5xx: retry with bounded exponential backoff when appropriate.- Preserve debugging context: HTTP status,
x-request-id, model, size, quality, output format, streaming mode, and last SSE event type.
References
Read references/api.md when you need complete endpoint parameters, curl examples, SDK examples, SSE parsing details, or troubleshooting tables.