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

# OpenAI Images Compatible Image Generation

> Use `POST /v1/images/generations` to call the unified image generation entry point, and select compatible models such as `gpt-image-1`, `dall-e-3`, and `dall-e-2` via `model`.

# OpenAI Images Compatible Image Generation

Submit text-to-image requests through the unified image generation entry point, and return an OpenAI Images-style response.

* A unified image generation API that selects different image models through `model`.
* Preserves the OpenAI Images response structure: `created` + `data[]`.
* Supports both `url` and `b64_json` response formats.
* Size restrictions for `dall-e-2` and `dall-e-3` are validated directly by the unified layer.
* When `n` is omitted or explicitly set to `0`, the unified layer automatically defaults it 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-1",
      "prompt": "A minimalist illustration for an API platform homepage, white background with teal accents",
      "n": 1,
      "size": "1024x1024",
      "quality": "auto",
      "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-1",
          "prompt": "A minimalist illustration for an API platform homepage, white background with teal accents",
          "n": 1,
          "size": "1024x1024",
          "quality": "auto",
          "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-1",
      prompt: "A minimalist illustration for an API platform homepage, white background with teal accents",
      n: 1,
      size: "1024x1024",
      quality: "auto",
      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 minimalist illustration for an API platform homepage, white background with teal accents"
      }
    ]
  }
  ```

  ```json 200 - Base64 theme={null}
  {
    "created": 1735689600,
    "data": [
      {
        "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...",
        "revised_prompt": "A minimalist illustration for an API platform homepage, white background with teal accents"
      }
    ]
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "message": "size must be one of 1024x1024, 1024x1792 or 1792x1024 for dall-e-3",
      "type": "invalid_request_error",
      "param": "",
      "code": "invalid_request"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "message": "Invalid API key provided",
      "type": "invalid_request_error",
      "param": "",
      "code": "invalid_api_key"
    }
  }
  ```

  ```json 402 theme={null}
  {
    "error": {
      "message": "User quota is insufficient",
      "type": "new_api_error",
      "param": "",
      "code": "insufficient_user_quota"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "message": "The current request rate is too high, please try again later",
      "type": "new_api_error",
      "param": "",
      "code": "too_many_requests"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "message": "bad response body",
      "type": "new_api_error",
      "param": "",
      "code": "bad_response_body"
    }
  }
  ```
</ResponseExample>

## Authentication

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

## Body

<ParamField body="model" type="string" required>
  Model name. The unified layer requires this field to be present.
</ParamField>

<ParamField body="prompt" type="string">
  Generation prompt. For image generation, it should be treated as required semantically; whether the request is ultimately blocked is determined jointly by the unified layer and the upstream provider.
</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. `dall-e-2` accepts only `256x256`, `512x512`, and `1024x1024`; `dall-e-3` accepts only `1024x1024`, `1024x1792`, and `1792x1024`.
</ParamField>

<ParamField body="quality" type="string">
  Image quality. `dall-e-3` defaults to `standard`; `gpt-image-1` defaults to `auto`.
</ParamField>

<ParamField body="response_format" type="string">
  Response format. Common values are `url` and `b64_json`. When `b64_json` or `base64` is requested, the unified layer returns Base64 image data.
</ParamField>

<ParamField body="style" type="string | object">
  Style field, passed through unchanged to supported upstream providers.
</ParamField>

<ParamField body="background" type="string | object">
  Background control field, passed through unchanged to supported upstream providers.
</ParamField>

<ParamField body="watermark" type="boolean">
  Explicit watermark switch. `false` is semantically different from omitting it: omission means the default strategy is used, while `false` explicitly disables it.
</ParamField>

## 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 upstream providers rewrite the prompt and return it in this field.
</ResponseField>

<ResponseField name="metadata" type="object">
  Additional metadata. Whether it exists depends on the specific channel.
</ResponseField>

## Use Cases

### Basic Image Generation

```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-1",
    "prompt": "Generate a clean product poster"
  }'
```

### High-Quality DALL·E 3

```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": "dall-e-3",
    "prompt": "A sci-fi city nightscape illustration",
    "size": "1792x1024",
    "quality": "hd",
    "response_format": "url"
  }'
```

### Base64 Output

```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-1",
    "prompt": "Generate a clean poster of an icon set",
    "response_format": "b64_json"
  }'
```

## Notes

<Warning>
  This page describes only the common semantics of the unified entry point, and does not mean that all image channels support exactly the same fields. Whether fields such as `style`, `background`, and `watermark` actually take effect depends on the final channel that is hit.
</Warning>

## Related APIs

* [OpenAI Images Compatible Overview](./overview)
* [OpenAI Images Compatible Image Editing](./edit)