/openrouter-images

name: openrouter-images
description: Generate images from text prompts and edit existing images using OpenRouter's dedicated Image API. Use when the user asks to create, generate, or make an image, picture, or illustration from a description, or wants to edit, modify, transform, or alter an existing image with a text prompt.

OpenRouter Images

Generate images from text prompts and edit existing images via OpenRouter's dedicated Image API (`POST /api/v1/images`). The skill also discovers which models exist and which parameters each one accepts, so you pick a valid model and options instead of guessing.

Prerequisites

The `OPENROUTER_API_KEY` environment variable must be set. Get a key at https://openrouter.ai/keys

Discovery (`discover.ts`) is public and works without a key; generation and editing require one.

First-Time Setup

cd <skill-path>/scripts && npm install

Decision Tree

Pick the right script based on what the user is asking:

| User wants to... | Script | Example | |---|---|---| | See which image models exist and what they support | `discover.ts` | "What image models can I use?" | | Check the exact params a specific model accepts | `discover.ts <model>` | "Does seedream support 4K?" | | Generate an image from a text description | `generate.ts "prompt"` | "Create an image of a sunset over mountains" | | Generate with specific options | `generate.ts "prompt" --aspect-ratio 16:9` | "Make a wide landscape image of a forest" | | Generate with a different model | `generate.ts "prompt" --model <id>` | "Generate using gemini 3.1 flash lite image" | | Edit or modify an existing image | `edit.ts path "prompt"` | "Make the sky purple in photo.png" | | Transform an image with instructions | `edit.ts path "prompt"` | "Add a party hat to the animal in this image" |

Discover Capabilities First

Different models accept different parameters. Rather than hardcoding flags and hitting 400s, discover what's available before generating.

List every image model with a compact capability summary:

cd <skill-path>/scripts && npx tsx discover.ts

Each entry reports the model `id`, `input_modalities` / `output_modalities` (image input means it supports editing / image-to-image), `supports_streaming`, and a `supported_parameters` map — the union of what any endpoint of that model accepts.

Inspect one model's definitive per-endpoint capabilities:

cd <skill-path>/scripts && npx tsx discover.ts bytedance-seed/seedream-4.5

This calls `GET /api/v1/images/models/{author}/{slug}/endpoints` and returns, per provider endpoint:

| Field | Meaning | |---|---| | `provider_name` / `provider_slug` | The serving provider. Use `provider_slug` as the key in `--provider-options`. | | `supported_parameters` | The exact parameters *this* endpoint accepts, with allowed values. | | `allowed_passthrough_parameters` | Provider-specific keys you can pass under `--provider-options` (e.g. `steps`, `guidance`). | | `supports_streaming` | Whether this endpoint streams. | | `pricing` | Per-image / per-token pricing lines. |

Capability values print as readable strings: an enum shows as `1K | 2K | 4K`, a range as `0–100`, a boolean as `supported`. A parameter that's absent is unsupported — don't send it.

Generate Image

Create a new image from a text prompt:

cd <skill-path>/scripts && npx tsx generate.ts "a red panda wearing sunglasses"
cd <skill-path>/scripts && npx tsx generate.ts "a futuristic cityscape at night" --aspect-ratio 16:9
cd <skill-path>/scripts && npx tsx generate.ts "pixel art of a dragon" --output dragon.png
cd <skill-path>/scripts && npx tsx generate.ts "a watercolor painting" --model google/gemini-3.1-flash-lite-image --resolution 1K

Edit Image

Modify an existing image with a text prompt. The source image is sent as an image-to-image reference (`input_references`), so use a model whose `input_modalities` include `image` — check with `discover.ts <model>`.

cd <skill-path>/scripts && npx tsx edit.ts photo.png "make the sky purple"
cd <skill-path>/scripts && npx tsx edit.ts avatar.jpg "add a party hat" --output avatar-hat.png
cd <skill-path>/scripts && npx tsx edit.ts scene.png "convert to watercolor style" --model google/gemini-3.1-flash-lite-image

Supported input formats: `.png`, `.jpg`, `.jpeg`, `.webp`, `.gif`

Options

Both `generate.ts` and `edit.ts` accept the same flags. Only pass parameters the target model supports — verify with `discover.ts <model>`.

| Flag | Description | Default | |---|---|---| | `--model <id>` | OpenRouter model ID | `google/gemini-3.1-flash-image-preview` | | `--output <path>` | Output file path | `image-YYYYMMDD-HHmmss.png` | | `--aspect-ratio <r>` | Aspect ratio (e.g. `16:9`, `1:1`, `4:3`) | Model default | | `--resolution <t>` | Resolution tier (`512`, `1K`, `2K`, `4K`) | Model default | | `--size <s>` | Shorthand: a tier (`2K`) or explicit pixels (`2048x2048`) | Model default | | `--quality <q>` | `auto`, `low`, `medium`, or `high` | Model default | | `--output-format <f>` | `png`, `jpeg`, `webp`, or `svg` (vector models) | Model default | | `--background <b>` | `auto`, `transparent`, or `opaque` | Model default | | `--output-compression <n>` | Compression 0–100 for webp/jpeg | Model default | | `--n <count>` | Number of images to generate (1–10, provider permitting) | 1 | | `--seed <int>` | Seed for deterministic generation (where supported) | Random | | `--provider-options <json>` | Provider-specific passthrough, keyed by `provider_slug` | None |

`--provider-options` takes a JSON object keyed by provider slug, using keys from that endpoint's `allowed_passthrough_parameters`:

cd <skill-path>/scripts && npx tsx generate.ts "a dramatic portrait" \
  --model black-forest-labs/flux.2-pro \
  --provider-options '{"black-forest-labs": {"steps": 40, "guidance": 3}}'

Output Format

generate.ts

{
  "model": "google/gemini-3.1-flash-image-preview",
  "prompt"