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

# GPT Image 2 — Text-to-Image

> Generate images from text prompts with OpenAI GPT Image 2.

|              |                          |
| ------------ | ------------------------ |
| **Model ID** | `openai/gpt-image-2-t2i` |
| **Family**   | `gpt-image-2`            |
| **Task**     | `text-to-image`          |
| **Provider** | OpenAI                   |
| **Modality** | Image                    |

## Parameters

<ParamField body="prompt" type="string" required>
  Text description of the image to generate. Maximum 32,000 characters.
</ParamField>

<ParamField body="quality" type="string">
  Render quality tier — directly affects cost. One of `low`, `medium`, `high`. Default: `medium`.
</ParamField>

<ParamField body="size" type="string">
  Output dimensions. One of `1024x1024`, `1024x1536`, `1536x1024`, `1024x2048`, `2048x1024`, `688x2048`, `2048x688`, `880x2048`, `2048x880`, `1152x2048`, `2048x1152`, `1360x2048`, `2048x1360`, `1536x2048`, `2048x1536`, `2048x2048`, `2160x3840`, `3840x2160`, `auto`. Default: `1024x1024`.
</ParamField>

<ParamField body="n" type="integer">
  Number of images to generate. Range: `1`–`10`. Default: `1`. Each image is
  billed its own output cost, so `n` images cost `n×` (you're charged only for
  images actually returned).
</ParamField>

<ParamField body="background" type="string">
  Background style. One of `transparent`, `opaque`, `auto`. Default: `auto`.
  `transparent` renders a true alpha channel and requires `output_format`
  `png` (the default) or `webp` — JPEG has no transparency.
</ParamField>

<ParamField body="output_format" type="string">
  Output file format. One of `png`, `jpeg`, `webp`. Default: `png`.
</ParamField>

<ParamField body="output_compression" type="integer">
  Output compression quality, `0`–`100`. JPEG only.
</ParamField>

<ParamField body="moderation" type="string">
  Moderation strictness. One of `low`, `auto`. Default: `auto`.
</ParamField>

<ParamField body="callback_url" type="string">
  HTTPS endpoint to POST the finished generation to. Delivered after the image
  is mirrored to storage, so it carries the final URL. Private and loopback
  addresses are rejected.
</ParamField>

<ParamField body="stream" type="boolean">
  Stream the result over SSE instead of answering immediately. Default: `false`.
  See [Getting the result](#getting-the-result).
</ParamField>

## Getting the result

Generation takes roughly 20-120 seconds, so the request does **not** return the
image. It returns the generation id right away:

```json theme={null}
{ "id": "a62fc882-...", "object": "image.generation", "status": "pending", "model": "openai/gpt-image-2-t2i" }
```

Collect the result in whichever of these three suits you.

### Poll (default)

```bash theme={null}
curl https://routerbase.com/v1/images/generations/a62fc882-... \
  -H "Authorization: Bearer sk-rb-xxxxxxxxxxxx"
```

`status` becomes `success` (read `data[0].url`) or `failed` (read
`error_message`).

### Webhook

Pass `callback_url` and we POST it once the image is stored:

```json theme={null}
{ "task_id": "a62fc882-...", "status": "success", "result_urls": ["https://..."], "error_message": null }
```

The URL must be publicly reachable over HTTPS; loopback, private-range and
cloud-metadata addresses are refused.

### Stream

Pass `"stream": true` for `text/event-stream`:

```
data: {"type":"image_generation.created","id":"a62fc882-...","status":"pending"}

data: {"type":"image_generation.completed","id":"a62fc882-...","status":"success","data":[{"url":"https://..."}]}

data: [DONE]
```

The first event arrives immediately, so you hold the id even if the connection
drops later. Streaming keeps the connection open for the whole generation --
if your client or a proxy times out below \~2 minutes, prefer polling or a
webhook. There is no progressive preview: the upstream sends the image only
when it is finished, so `partial_images` has no effect.

<Note>
  Send an `Idempotency-Key` header with every request. If the connection drops,
  repeating the request with the same key returns the original generation instead
  of creating and charging a second one. See
  [Idempotency](/essentials/idempotency).
</Note>

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://routerbase.com/v1/images/generations \
    -H "Authorization: Bearer sk-rb-xxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai/gpt-image-2-t2i",
      "prompt": "An isometric pixel-art coffee shop, warm evening light",
      "quality": "high",
      "size": "1536x1024"
    }'
  ```

  ```python Python theme={null}
  from openai import OpenAI

  client = OpenAI(
      api_key="sk-rb-xxxxxxxxxxxx",
      base_url="https://routerbase.com/v1",
  )

  img = client.images.generate(
      model="openai/gpt-image-2-t2i",
      prompt="An isometric pixel-art coffee shop, warm evening light",
      extra_body={"quality": "high", "size": "1536x1024"},
  )
  print(img.data[0].url)
  ```
</CodeGroup>