openrouterteam/openrouter-images

OpenRouter Images

Generate images from text prompts and edit existing images via OpenRouter's chat completions API with image modalities.

Prerequisites

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

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 | |---|---|---| | Generate an image from a text description | generate.ts "prompt" | "Create an image of a sunset over mountains" | | Generate with specific aspect ratio | 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-2.5-flash-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" |

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-2.5-flash-image

Options

| 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 | | --image-size <s> | Image size (e.g. 1K, 2K) | Model default |

Edit Image

Modify an existing image with a text prompt:

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-2.5-flash-image

Options

| 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 | | --image-size <s> | Image size (e.g. 1K, 2K) | Model default |

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

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
}

API Response Shapes

Image generation uses POST /api/v1/responses with modalities: ["image", "text"]. See the Responses API reference and image generation guide for full request details.

The image-specific output item type is image_generation_call — this is not obvious from the general Responses API docs:

{
  "type": "image_generation_call",
  "id": "imagegen-abc123",
  "status": "completed",
  "result": "<base64-encoded image data>"
}

This appears alongside standard message output items in the output array. Text and image outputs may each be absent depending on the model and prompt.

Using a Different Model

The default model is google/gemini-3.1-flash-image-preview (Nano Banana 2). To use a different model, pass --model <id> with any OpenRouter model ID that supports image output modalities.

Use the openrouter-models skill to discover image-capable models:

cd <openrouter-models-skill-path>/scripts && npx tsx search-models.ts --modality image

Presenting Results

• After generating or editing, display the saved image to the user
• Include the model used and any text response the model provided (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