---
name: imagerouter
description: Generate images and videos with any AI model on ImageRouter (requires API key).
homepage: https://imagerouter.io
metadata: {"openclaw":{"emoji":"🎨","requires":{"bins":["curl"]},"primaryEnv":"IMAGEROUTER_API_KEY"}}
---

# [ImageRouter](https://imagerouter.io) AI Generation

Generate images and videos with any AI model available on [ImageRouter](https://imagerouter.io). Full docs: https://docs.imagerouter.io

## OpenClaw Setup

- This skill expects your ImageRouter key in the environment variable `IMAGEROUTER_API_KEY`.
- **Do not paste API keys into chat**. Set the env var in the OpenClaw Gateway environment (in terminal) and restart the gateway. Example:
```bash
openclaw config set skills.entries.imagerouter.apiKey "your_api_key_here"
openclaw gateway restart
```

## Available models

Get top 10 most popular models:
```bash
curl -X POST 'https://backend.imagerouter.io/operations/get-popular-models'
```

### Models API

```
GET /v3/models          # list all models
GET /v3/models/:modelId # single model (URL-encode "/", e.g. openai%2Fgpt-image-2)
```

Note: `test/test` (image) and `ir/test-video` (video) are free dummy models for testing only — use real models for actual output.

### Query Parameters

| Parameter           | Description |
|---------------------|-------------|
| `output_modalities` | Filter by output: `image`, `video`, or `text` |
| `input_modalities`  | Filter by supported input: `image`, `mask`, `text`, `audio`, `video` |
| `provider`          | Provider name, partial/case-insensitive (e.g. `google`, `openai`) |
| `free`              | `true` = free only, `false` = paid only |
| `name`              | Model name or alias, partial/case-insensitive |
| `sort`              | `name`, `provider`, `price`, or `date` (newest first) |
| `limit`             | Max models to return |
| `fields`            | Comma-separated fields to include (`id` always present) |

### Fields

`id`, `architecture` (`input_modalities`/`output_modalities`), `created` (Unix seconds), `pricing` (`min`/`average`/`max` USD for image/video; per-token object for text), `supported_parameters` (e.g. `quality`, `size`, `seconds`, `mask`), `parameters` (allowed values for `size`/`seconds`), `aliases`, `context_length` (text models).

### Examples

```bash
# All model ids and aliases
curl "https://api.imagerouter.io/v3/models?fields=id,aliases"

# Free image models with capabilities
curl "https://api.imagerouter.io/v3/models?output_modalities=image&free=true&fields=id,aliases,architecture"

# Image-editing models (accept input images)
curl "https://api.imagerouter.io/v3/models?input_modalities=image&output_modalities=image"

# Video models with pricing, newest first
curl "https://api.imagerouter.io/v3/models?output_modalities=video&sort=date&fields=pricing,parameters"

# Search by name/alias
curl "https://api.imagerouter.io/v3/models?name=gemini"
```

## Quick Start - Text-to-Image

Basic generation with JSON endpoint:
```bash
curl 'https://api.imagerouter.io/v1/openai/images/generations' \
  -H "Authorization: Bearer $IMAGEROUTER_API_KEY" \
  --json '{
    "prompt": "a serene mountain landscape at sunset",
    "model": "test/test",
    "quality": "auto",
    "size": "auto",
    "response_format": "url",
    "output_format": "webp"
  }'
```

## Unified Endpoint (Text-to-Image & Image-to-Image)

### Text-to-Image with multipart/form-data:
```bash
curl 'https://api.imagerouter.io/v1/openai/images/edits' \
  -H "Authorization: Bearer $IMAGEROUTER_API_KEY" \
  -F 'prompt=a cyberpunk city at night' \
  -F 'model=test/test' \
  -F 'quality=high' \
  -F 'size=1024x1024' \
  -F 'response_format=url' \
  -F 'output_format=webp'
```

### Image-to-Image (with input images):
```bash
curl 'https://api.imagerouter.io/v1/openai/images/edits' \
  -H "Authorization: Bearer $IMAGEROUTER_API_KEY" \
  -F 'prompt=transform this into a watercolor painting' \
  -F 'model=test/test' \
  -F 'quality=auto' \
  -F 'size=auto' \
  -F 'response_format=url' \
  -F 'output_format=webp' \
  -F 'image[]=@/path/to/your/image.webp'
```

### Multiple images (up to 16):
```bash
curl 'https://api.imagerouter.io/v1/openai/images/edits' \
  -H "Authorization: Bearer $IMAGEROUTER_API_KEY" \
  -F 'prompt=combine these images' \
  -F 'model=test/test' \
  -F 'image[]=@image1.webp' \
  -F 'image[]=@image2.webp' \
  -F 'image[]=@image3.webp'
```

### With mask (some models require mask for inpainting):
```bash
curl 'https://api.imagerouter.io/v1/openai/images/edits' \
  -H "Authorization: Bearer $IMAGEROUTER_API_KEY" \
  -F 'prompt=fill the masked area with flowers' \
  -F 'model=test/test' \
  -F 'image[]=@original.webp' \
  -F 'mask[]=@mask.webp'
```

## Parameters

- **model** (required): Image model to use (see https://imagerouter.io/models)
- **prompt** (optional): Text description for generation. Most models require a text prompt, but not all.
- **quality** (optional): `auto` (default), `low`, `medium`, `high`
- **size** (optional): `auto` (default) or `WIDTHxHEIGHT` (e.g., `1024x1024`).
- **response_format** (optional): 
  - `url` (default) - Returns hosted URL
  - `b64_json` - Returns base64-encoded image
  - `b64_ephemeral` - Base64 without saving to logs
- **output_format** (optional): `webp` (default), `jpeg`, `png`
- **image[]** (optional): Input file for Image-to-Image (multipart only)
- **mask[]** (optional): Editing mask for inpainting (multipart only)

## Response Format

```json
{
  "created": 1769286389027,
  "data": [
    {
      "url": "https://storage.imagerouter.io/fffb4426-efbd-4bcc-87d5-47e6936bf0bb.webp"
    }
  ],
  "latency": 6942,
  "cost": 0.004
}
```

## Endpoint Comparison

| Feature | Unified (/edits) | JSON (/generations) |
|---------|------------------|---------------------|
| Text-to-Image | ✅ | ✅ |
| Image-to-Image | ✅ | ❌ |
| Encoding | multipart/form-data | application/json |

## Tips

- Both `/v1/openai/images/generations` and `/v1/openai/images/edits` are the same for the unified endpoint
- Use JSON endpoint for simple text-to-image when you don't need file uploads
- Use unified endpoint when you need Image-to-Image capabilities
- Check model features at https://imagerouter.io/models (quality support, edit support, etc.)
- Get your API key at https://imagerouter.io/api-keys

## Examples by Use Case

### Quick test generation:
```bash
curl 'https://api.imagerouter.io/v1/openai/images/generations' \
  -H "Authorization: Bearer $IMAGEROUTER_API_KEY" \
  --json '{"prompt":"test image","model":"test/test"}'
```

### Download image directly:
```bash
curl 'https://api.imagerouter.io/v1/openai/images/generations' \
  -H "Authorization: Bearer $IMAGEROUTER_API_KEY" \
  --json '{"prompt":"abstract art","model":"test/test"}' \
  | jq -r '.data[0].url' \
  | xargs curl -o output.webp
```

## Text / LLM Generation

ImageRouter is a drop-in OpenAI-compatible gateway for chat/LLM models. Use the same `IMAGEROUTER_API_KEY`.

Find text models with:
```bash
curl "https://api.imagerouter.io/v3/models?output_modalities=text&fields=id,aliases,pricing,context_length"
```

### Chat Completions

```bash
curl 'https://api.imagerouter.io/v1/openai/chat/completions' \
  -H "Authorization: Bearer $IMAGEROUTER_API_KEY" \
  --json '{
    "model": "openai/gpt-5",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Write a haiku about the ocean."}
    ]
  }'
```

Standard OpenAI chat-completion parameters (`temperature`, `max_tokens`, `top_p`, `tools`, etc.) are passed through unchanged.

### Streaming

Set `"stream": true` to receive Server-Sent Events:
```bash
curl 'https://api.imagerouter.io/v1/openai/chat/completions' \
  -H "Authorization: Bearer $IMAGEROUTER_API_KEY" \
  --json '{
    "model": "openai/gpt-5",
    "messages": [{"role": "user", "content": "Count to five."}],
    "stream": true
  }'
```

### Vision / Image Input

Multimodal models accept image parts in message content:
```bash
curl 'https://api.imagerouter.io/v1/openai/chat/completions' \
  -H "Authorization: Bearer $IMAGEROUTER_API_KEY" \
  --json '{
    "model": "openai/gpt-5",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "What is in this image?"},
        {"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}}
      ]
    }]
  }'
```

### Responses API

The OpenAI Responses API is also supported at `/v1/openai/responses` (same auth, streaming via `"stream": true`):
```bash
curl 'https://api.imagerouter.io/v1/openai/responses' \
  -H "Authorization: Bearer $IMAGEROUTER_API_KEY" \
  --json '{
    "model": "openai/gpt-5",
    "input": "Write a haiku about the ocean."
  }'
```

### LLM Parameters

- **model** (required): Text model id or alias (see text models query above)
- **messages** (required for `/chat/completions`): OpenAI-style message array
- **input** (required for `/responses`): Prompt string or input items
- **stream** (optional): `true` to stream SSE responses
- All other OpenAI chat/responses parameters (`temperature`, `max_tokens`, `top_p`, `tools`, `response_format`, etc.) pass through unchanged.

Billing is per-token based on the model's pricing; the returned `usage` reflects the actual cost.