> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/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](/ai-gateway/features/server-tools).

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST https://my.orq.ai/v3/router/responses \
    -H "Authorization: Bearer $ORQ_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)
  ```
</CodeGroup>

The tool returns `status`, `model`, and `image_url` to the calling model. **Orq.ai** 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`.