> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Image generation server tool

> Let a model generate an image during a Responses API request with a configured image model.

The `orq:image_generation` tool lets a text model create an image during a response. The tool entry selects the image model and rendering options. The calling model supplies only the image prompt.

This tool is available on `POST /v3/router/responses` only. Chat Completions returns `400` for a request that includes it.

## Quick start

The examples use the client configuration from the [Server tools overview](/docs/ai-gateway/features/server-tools.md).

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://router.toqan.ai/eu/v3/router/responses \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4-mini",
    "input": "Create a square product illustration of a green desk lamp.",
    "tools": [
      {
        "type": "orq:image_generation",
        "model": "openai/gpt-image-2",
        "size": "1024x1024",
        "quality": "high"
      }
    ]
  }'
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const response = await client.responses.create({
  model: 'openai/gpt-5.4-mini',
  input: 'Create a square product illustration of a green desk lamp.',
  tools: [
    {
      type: 'orq:image_generation',
      model: 'openai/gpt-image-2',
      size: '1024x1024',
      quality: 'high',
    },
  ] as any,
});

console.log(response.output_text);
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
response = client.responses.create(
    model="openai/gpt-5.4-mini",
    input="Create a square product illustration of a green desk lamp.",
    tools=[
        {
            "type": "orq:image_generation",
            "model": "openai/gpt-image-2",
            "size": "1024x1024",
            "quality": "high",
        }
    ],
)

print(response.output_text)
```

The tool returns `status`, `model`, and `image_url` to the calling model. **Toqan Router** stores the generated image in workspace storage when uploads are available and adds `image_path` as the durable storage reference. In that case `image_url` is a presigned link that expires after 7 days, so persist `image_path` rather than the URL. When storage is unavailable, `image_url` is a provider-hosted URL and `image_path` is absent.

## Configuration

| Parameter | Type | Required | Description |
| - | - | - | - |
| `type` | string | Yes | Must be `orq:image_generation`. |
| `model` | string | Yes | Image model in `provider/model` format. |
| `size` | string | No | Image dimensions supported by the selected model. |
| `quality` | string | No | Image quality supported by the selected model. |
| `background` | string | No | Background option supported by the selected model. |
| `output_format` | string | No | Output format supported by the selected model. |
| `output_compression` | integer | No | Compression level from 0 to 100, when supported. |
| `moderation` | string | No | Moderation setting supported by the selected model. |
| `style` | string | No | Image style supported by the selected model. |

Rendering options are model-dependent. Unsupported values return an error from the selected image provider.

## Cost and usage

The image model call is billed at the selected model's standard rate. Each tool call appears at `usage.server_tool_use.image_generation_calls`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.