openrouter-images

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:

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:

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>.

--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": "a red panda wearing sunglasses",
  "images_saved": ["/absolute/path/to/image-20260305-143022.png"],
  "count": 1
}

edit.ts

{
  "model": "google/gemini-3.1-flash-image-preview",
  "source_image": "photo.png",
  "prompt": "make the sky purple",
  "images_saved": ["/absolute/path/to/image-20260305-143055.png"],
  "count": 1
}

The generation cost (USD) is printed to stderr when the API reports it. When --n requests multiple images, each is saved with a -1, -2, … suffix.

API Response Shapes

Generation uses POST /api/v1/images. See the Image Generation guide for full request/response details.

Images come back base64-encoded in a data array. For raster PNG output, media_type is omitted; vector outputs (e.g. SVG) include it, and the saved file extension follows it:

{
  "created": 1748372400,
  "data": [{ "b64_json": "<base64-encoded image data>" }],
  "usage": { "prompt_tokens": 0, "completion_tokens": 4175, "total_tokens": 4175, "cost": 0.04 }
}

Using a Different Model

The default model is google/gemini-3.1-flash-image-preview (Nano Banana 2). To use another, pass --model <id> with any image model ID (e.g. google/gemini-3.1-flash-lite-image). Run discover.ts to browse image models and discover.ts <model> to confirm which parameters and providers it supports before generating.

Presenting Results

• After generating or editing, display the saved image to the user
• Include the model used and, when reported, the generation cost (printed to stderr)
• If multiple images are returned, show all of them
• When the user doesn't specify an output path, tell them where the file was saved
• For edit operations, mention the source image that was modified