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

# gpt-image-2 Image Generation API

> Use `POST /v1/images/generations` to call the unified image generation entry for `gpt-image-2`.

# gpt-image-2 Image Generation API

`gpt-image-2` uses a unified image generation entry, suitable for text-to-image requests based on standard ratios and size tiers.

* The unified entry is `POST /v1/images/generations`.
* Select the target model by setting `model = "gpt-image-2"`.
* Supports both `url` and `b64_json` response formats.
* You can include `image` in JSON as a reference image; whether it takes effect depends on the actual image channel that is matched.
* If `n` is omitted or explicitly set to `0`, the unified layer falls back to `1`.

## Method and Path

```http theme={null}
POST /v1/images/generations
```

## Request Example

<CodeGroup>
  ```bash theme={null}
  curl -X POST https://octopusx.ai/v1/images/generations \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-image-2",
      "prompt": "A modern homepage illustration for an API platform, white background, teal-blue blocks, clean whitespace",
      "n": 1,
      "size": "1536x1024",
      "response_format": "url"
    }'
  ```

  ```python theme={null}
  import requests

  resp = requests.post(
      "https://octopusx.ai/v1/images/generations",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      json={
          "model": "gpt-image-2",
          "prompt": "A modern homepage illustration for an API platform, white background, teal-blue blocks, clean whitespace",
          "n": 1,
          "size": "1536x1024",
          "response_format": "url",
      },
      timeout=60,
  )
  print(resp.json())
  ```

  ```javascript theme={null}
  const response = await fetch("https://octopusx.ai/v1/images/generations", {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "gpt-image-2",
      prompt: "A modern homepage illustration for an API platform, white background, teal-blue blocks, clean whitespace",
      n: 1,
      size: "1536x1024",
      response_format: "url",
    }),
  });

  console.log(await response.json());
  ```
</CodeGroup>

## Response Example

<ResponseExample>
  ```json 200 - URL theme={null}
  {
    "created": 1735689600,
    "data": [
      {
        "url": "https://.../images/img-abc123.png",
        "revised_prompt": "A modern homepage illustration for an API platform, white background, teal-blue blocks, clean whitespace"
      }
    ]
  }
  ```

  ```json 200 - Base64 theme={null}
  {
    "created": 1735689600,
    "data": [
      {
        "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...",
        "revised_prompt": "A modern homepage illustration for an API platform, white background, teal-blue blocks, clean whitespace"
      }
    ]
  }
  ```
</ResponseExample>

## Authentication

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Body

<ParamField body="model" type="string" required>
  Must be set to `gpt-image-2`.
</ParamField>

<ParamField body="prompt" type="string">
  Generation prompt. For text-to-image semantics, this should be treated as required.
</ParamField>

<ParamField body="n" type="integer">
  Number of images to generate. If omitted or explicitly set to `0`, the unified layer falls back to `1`.
</ParamField>

<ParamField body="size" type="string">
  Output size. Common base tiers are `1024x1024`、`1536x1152`、`1536x1024`、`1024x1536`、`1920x1080`、`1080x1920`.
</ParamField>

<ParamField body="image" type="string | array<string> | object">
  Optional reference image input. Commonly written as a Base64 string or Base64 array, suitable for channels that require image style reference.
</ParamField>

<ParamField body="response_format" type="string">
  Response format. Common values are `url` and `b64_json`.
</ParamField>

<ParamField body="quality" type="string">
  Quality field. Whether it actually takes effect depends on the final matched channel.
</ParamField>

<ParamField body="style" type="string | object">
  Style field, passed through as-is to supported upstreams.
</ParamField>

<ParamField body="background" type="string | object">
  Background control field, passed through as-is to supported upstreams.
</ParamField>

<ParamField body="watermark" type="boolean">
  Explicit watermark switch. `false` and omission have different semantics.
</ParamField>

## Base Ratios and Size Tiers

| Preset | Actual Target Size |
| ------ | ------------------ |
| `1:1`  | `1024x1024`        |
| `4:3`  | `1536x1152`        |
| `3:2`  | `1536x1024`        |
| `2:3`  | `1024x1536`        |
| `16:9` | `1920x1080`        |
| `9:16` | `1080x1920`        |

<Info>
  If the actual channel does not natively accept the target size, the gateway or plugin will fall back to a closer official size and append the ratio intent to the prompt.
</Info>

## Response

<ResponseField name="created" type="integer">
  Generation timestamp.
</ResponseField>

<ResponseField name="data[].url" type="string">
  The image URL returned when `response_format = url`.
</ResponseField>

<ResponseField name="data[].b64_json" type="string">
  The Base64 image data returned when `response_format = b64_json`.
</ResponseField>

<ResponseField name="data[].revised_prompt" type="string">
  Some upstreams rewrite the prompt and return it in this field.
</ResponseField>

## Related APIs

* [Image Model Support Matrix](/en/images/model-matrix)
* [OpenAI Images Compatibility Overview](/en/images/gpt-image-1/overview)