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

# Images introduction

# OpenAI Async Image API

A **single unified endpoint** for both text-to-image generation and image editing. The operation type is auto-detected based on whether you provide an `image` field in the request body.

## Supported Model

| Model         | Description               |
| ------------- | ------------------------- |
| `gpt-image-2` | Latest OpenAI image model |

## How It Works

<Steps>
  <Step title="Create a task">
    Call `POST /openai/images` with your prompt. The endpoint auto-detects the operation:

    * **No `image` field** → text-to-image generation
    * **With `image` field** → image editing
    * **With `image` + `mask`** → inpainting (transparent mask areas are repainted)

    Returns `{ "taskId": "..." }`.
  </Step>

  <Step title="Poll for results">
    Call `GET /openai/tasks?taskId=<taskId>` until `status` is `completed` or `failed`.
  </Step>

  <Step title="Use the result">
    The task `result` field contains the generated image (base64 encoded by default for gpt-image-2).
  </Step>
</Steps>

## Quick Examples

<CodeGroup>
  ```bash Text-to-Image theme={null}
  curl -X POST "https://api.mountsea.ai/openai/images" \
    -H "Authorization: Bearer your-api-key" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "A photorealistic cat wearing a space helmet, floating in orbit",
      "model": "gpt-image-2",
      "size": "1024x1024",
      "quality": "high"
    }'
  ```

  ```bash Image Edit (URL) theme={null}
  curl -X POST "https://api.mountsea.ai/openai/images" \
    -H "Authorization: Bearer your-api-key" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "Add a vintage film grain and warm color tone",
      "model": "gpt-image-2",
      "image": "https://example.com/source.jpg",
      "size": "1024x1024",
      "input_fidelity": "high"
    }'
  ```

  ```bash Image Edit (base64) theme={null}
  curl -X POST "https://api.mountsea.ai/openai/images" \
    -H "Authorization: Bearer your-api-key" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "Make the sky dramatic with stormy clouds",
      "model": "gpt-image-2",
      "image": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
      "size": "1024x1024"
    }'
  ```

  ```bash Inpainting (with mask) theme={null}
  curl -X POST "https://api.mountsea.ai/openai/images" \
    -H "Authorization: Bearer your-api-key" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "Replace the background with a sunset beach",
      "model": "gpt-image-2",
      "image": "https://example.com/source.png",
      "mask": "https://example.com/mask.png"
    }'
  ```

  ```bash Poll Task Status theme={null}
  curl -X GET "https://api.mountsea.ai/openai/tasks?taskId=your-task-id" \
    -H "Authorization: Bearer your-api-key"
  ```
</CodeGroup>

## Parameters

| Field                | Type               | Required | Description                                                                           |
| -------------------- | ------------------ | -------- | ------------------------------------------------------------------------------------- |
| `prompt`             | string             | ✅        | Prompt describing the desired image (for editing: describe the modification)          |
| `model`              | string             | —        | Defaults to `gpt-image-2`                                                             |
| `size`               | enum               | —        | `auto`, `1024x1024` (default), `1024x1536`, `1536x1024`                               |
| `n`                  | number             | —        | Generation count (currently only 1 supported)                                         |
| `quality`            | enum               | —        | `auto`, `low`, `medium`, `high`, `standard`                                           |
| `background`         | enum               | —        | `transparent`, `opaque`, `auto`                                                       |
| `output_format`      | enum               | —        | `png` / `jpeg` / `webp`                                                               |
| `output_compression` | number             | —        | JPEG/WebP compression 0-100                                                           |
| `moderation`         | enum               | —        | `auto`, `low`                                                                         |
| `response_format`    | enum               | —        | `url` or `b64_json` (gpt-image-2 always returns b64\_json)                            |
| `input_fidelity`     | enum               | —        | `high` or `low` — only for edit; controls how closely the output follows the input    |
| `image`              | string / string\[] | —        | URL or base64 data URL. **Presence triggers editing mode.** Single or multiple images |
| `mask`               | string             | —        | Mask image (URL or base64). Transparent areas will be repainted. Edit-only            |

## Task Status

| Status       | Meaning                                   |
| ------------ | ----------------------------------------- |
| `pending`    | Task created, awaiting processing         |
| `ready`      | Ready for assignment                      |
| `assigned`   | Assigned to a worker                      |
| `processing` | Actively generating                       |
| `completed`  | Done — `result` contains the image        |
| `failed`     | Failed — see `errorMessage` / `errorCode` |
| `cancelled`  | Cancelled by user or system               |
| `timeout`    | Exceeded processing timeout               |

<Tip>
  Poll every **2-5 seconds**. Tasks typically complete in 10-60 seconds depending on quality and size.
</Tip>

## Available Endpoints

| Endpoint         | Method | Description                          |
| ---------------- | ------ | ------------------------------------ |
| `/openai/images` | POST   | Create image task (generate or edit) |
| `/openai/tasks`  | GET    | Get task status / result by taskId   |

***

### Explore the API Documentation

* [Create Image Task](images) — Async generate / edit / inpaint
* [Get Task Result](task) — Poll task status and get results

<Info>
  Looking for the **synchronous** OpenAI-compatible API? See [OpenAI Compat](/api-reference/openai/compat-introduction) to use the official `openai` SDK.
</Info>