> ## 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.

# Image Generation

> OpenAI-compatible image generation. Synchronous — the response holds until the image is ready.

## Endpoint

```
POST https://routerbase.com/v1/images/generations
```

Compatible with OpenAI's [Image Generation API](https://platform.openai.com/docs/api-reference/images). The connection is held open until the upstream model returns (typically 5–30 seconds).

## Request Headers

| Header          | Value                       |
| --------------- | --------------------------- |
| `Authorization` | `Bearer sk-rb-xxxxxxxxxxxx` |
| `Content-Type`  | `application/json`          |

## Request Body

<ParamField body="model" type="string" required>
  Image model ID. e.g. `google/imagen-4`, `blackforestlabs/flux-2-pro`, `ideogram/ideogram-3-0`.
</ParamField>

<ParamField body="prompt" type="string" required>
  Text description of the image to generate.
</ParamField>

<ParamField body="n" type="integer">
  Number of images to generate. Default `1`.
</ParamField>

<ParamField body="aspect_ratio" type="string">
  e.g. `1:1`, `16:9`, `9:16`, `4:3`, `3:4`. Model-dependent — not all models honor this.
</ParamField>

<ParamField body="resolution" type="string">
  e.g. `1K`, `2K`, `4K`. Model-dependent.
</ParamField>

<ParamField body="quality" type="string">
  e.g. `hd`, `standard`. Model-dependent.
</ParamField>

<ParamField body="style" type="string">
  e.g. `natural`, `vivid`. Model-dependent.
</ParamField>

<ParamField body="negative_prompt" type="string">
  What to exclude from the image. Model-dependent.
</ParamField>

<ParamField body="image_urls" type="array">
  Required for image-to-image / editing / upscale / reframe / remix models. Each entry may be a public HTTPS URL **or** an inline base64 `data:` URI (e.g. `data:image/png;base64,…`) — inline images are decoded and hosted automatically before generation, so no provider-specific handling is needed. For anything larger than a few MB, prefer uploading via `POST /v1/uploads` and passing the returned URL.
</ParamField>

## Examples

<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": "google/imagen-4",
      "prompt": "A red apple on a white table",
      "aspect_ratio": "1:1",
      "resolution": "1K"
    }'
  ```

  ```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="google/imagen-4",
      prompt="A red apple on a white table",
      extra_body={"aspect_ratio": "1:1", "resolution": "1K"},
  )
  print(img.data[0].url)
  ```
</CodeGroup>

## Response

```json theme={null}
{
  "created": 1776245700,
  "data": [
    { "url": "https://media.routerbase.com/media/<user>/<gen>/0.png" }
  ]
}
```

When R2 storage is configured, RouterBase rehosts upstream URLs on its own CDN so the links don't expire.

## Image-to-image

For i2i / editing models (e.g. `blackforestlabs/flux-2-pro-i2i`, `ideogram/ideogram-character-edit`), supply `image_urls`:

```json theme={null}
{
  "model": "blackforestlabs/flux-2-pro-i2i",
  "prompt": "Make it watercolor",
  "image_urls": ["https://example.com/source.jpg"]
}
```