Image Generation

The openrouter:image_generation server tool enables any model to generate images from text prompts. When the model determines it needs to create an image, it calls the tool with a description. OpenRouter executes the image generation and returns the result to the model.

How It Works

1. You include { "type": "openrouter:image_generation" } in your tools array.
2. Based on the user’s request, the model decides whether image generation is needed and crafts a prompt.
3. OpenRouter generates the image using the configured model (defaults to openai/gpt-image-1).
4. The generated image URL is returned to the model.
5. The model incorporates the image into its response. It may generate multiple images in a single request if needed.

Quick Start

1
const response = await fetch('https://openrouter.ai/api/v1/chat/completions', {
2
  method: 'POST',
3
  headers: {
4
    Authorization: 'Bearer {{API_KEY_REF}}',
5
    'Content-Type': 'application/json',
6
  },
7
  body: JSON.stringify({
8
    model: '{{MODEL}}',
9
    messages: [
10
      {
11
        role: 'user',
12
        content: 'Create an image of a futuristic city at sunset'
13
      }
14
    ],
15
    tools: [
16
      { type: 'openrouter:image_generation' }
17
    ]
18
  }),
19
});
20
21
const data = await response.json();
22
console.log(data.choices[0].message.content);

Configuration

The image generation tool accepts optional parameters to customize the output:

1
{
2
  "type": "openrouter:image_generation",
3
  "parameters": {
4
    "model": "openai/gpt-image-1",
5
    "quality": "high",
6
    "aspect_ratio": "16:9",
7
    "size": "1024x1024",
8
    "background": "transparent",
9
    "output_format": "png"
10
  }
11
}

All parameters except model are passed directly to the underlying image generation API. Available options depend on the specific model being used.

Response

When the model calls the image generation tool, it receives a response like:

1
{
2
  "status": "ok",
3
  "imageUrl": "https://..."
4
}

If generation fails, the response includes an error:

1
{
2
  "status": "error",
3
  "error": "Generation failed due to content policy"
4
}

Works with the Responses API

The image generation server tool also works with the Responses API:

1
const response = await fetch('https://openrouter.ai/api/v1/responses', {
2
  method: 'POST',
3
  headers: {
4
    Authorization: 'Bearer {{API_KEY_REF}}',
5
    'Content-Type': 'application/json',
6
  },
7
  body: JSON.stringify({
8
    model: '{{MODEL}}',
9
    input: 'Generate an image of a mountain landscape',
10
    tools: [
11
      {
12
        type: 'openrouter:image_generation',
13
        parameters: { quality: 'high' }
14
      }
15
    ]
16
  }),
17
});
18
19
const data = await response.json();
20
console.log(data);

Pricing

Image generation pricing depends on the underlying model used:

• openai/gpt-image-1: See OpenAI pricing
• Other models: See the model’s pricing page on OpenRouter

The cost is in addition to standard LLM token costs for processing the request and response.

Next Steps

• Server Tools Overview — Learn about server tools
• Web Search — Search the web for real-time information
• Datetime — Get the current date and time
• Tool Calling — Learn about user-defined tool calling