> ## 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 异步图像接口

**统一端点**，同时支持文生图和图像编辑。根据请求体中是否包含 `image` 字段自动判断操作类型。

## 支持的模型

| 模型            | 说明            |
| ------------- | ------------- |
| `gpt-image-2` | OpenAI 最新图像模型 |

## 工作流程

<Steps>
  <Step title="创建任务">
    调用 `POST /openai/images` 并传入 prompt。接口会自动判断操作类型：

    * **不传 `image`** → 文生图
    * **传 `image`** → 图像编辑
    * **传 `image` + `mask`** → 局部重绘（mask 透明区域被重绘）

    返回 `{ "taskId": "..." }`。
  </Step>

  <Step title="轮询结果">
    调用 `GET /openai/tasks?taskId=<taskId>`，直到 `status` 变为 `completed` 或 `failed`。
  </Step>

  <Step title="使用结果">
    任务 `result` 字段包含生成的图像（gpt-image-2 默认返回 base64 编码）。
  </Step>
</Steps>

## 快速示例

<CodeGroup>
  ```bash 文生图 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 图像编辑（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 图像编辑（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 局部重绘（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 轮询任务状态 theme={null}
  curl -X GET "https://api.mountsea.ai/openai/tasks?taskId=your-task-id" \
    -H "Authorization: Bearer your-api-key"
  ```
</CodeGroup>

## 参数说明

| 字段                   | 类型                 | 必填 | 说明                                              |
| -------------------- | ------------------ | -- | ----------------------------------------------- |
| `prompt`             | string             | ✅  | 提示词（编辑时描述修改内容）                                  |
| `model`              | string             | —  | 默认 `gpt-image-2`                                |
| `size`               | enum               | —  | `auto`、`1024x1024`（默认）、`1024x1536`、`1536x1024`  |
| `n`                  | number             | —  | 生成数量（目前仅支持 1）                                   |
| `quality`            | enum               | —  | `auto`、`low`、`medium`、`high`、`standard`         |
| `background`         | enum               | —  | `transparent`、`opaque`、`auto`                   |
| `output_format`      | enum               | —  | `png` / `jpeg` / `webp`                         |
| `output_compression` | number             | —  | JPEG/WebP 压缩等级 0-100                            |
| `moderation`         | enum               | —  | `auto`、`low`                                    |
| `response_format`    | enum               | —  | `url` 或 `b64_json`（gpt-image-2 总是返回 b64\_json）  |
| `input_fidelity`     | enum               | —  | `high` 或 `low`，仅编辑场景生效，控制输出与输入图的相似度             |
| `image`              | string / string\[] | —  | 图像 URL 或 base64 data URL。**传此字段触发编辑模式**，支持单张或多张 |
| `mask`               | string             | —  | Mask 图（URL 或 base64），透明区域将被重绘，仅编辑场景             |

## 任务状态

| 状态           | 含义                                    |
| ------------ | ------------------------------------- |
| `pending`    | 任务已创建，等待处理                            |
| `ready`      | 准备分配                                  |
| `assigned`   | 已分配到 worker                           |
| `processing` | 正在生成                                  |
| `completed`  | 完成 —— `result` 包含图像                   |
| `failed`     | 失败 —— 查看 `errorMessage` / `errorCode` |
| `cancelled`  | 已取消                                   |
| `timeout`    | 处理超时                                  |

<Tip>
  建议每 **2-5 秒** 轮询一次。任务通常在 10-60 秒内完成，具体取决于质量与尺寸。
</Tip>

## 可用端点

| 端点               | 方法   | 描述                    |
| ---------------- | ---- | --------------------- |
| `/openai/images` | POST | 创建图像任务（生成或编辑）         |
| `/openai/tasks`  | GET  | 通过 taskId 查询任务状态 / 结果 |

***

### 浏览 API 文档

* [创建图像任务](images) —— 异步生成 / 编辑 / 重绘
* [获取任务结果](task) —— 轮询任务状态并获取结果

<Info>
  需要**同步** OpenAI 兼容接口？查看 [OpenAI 兼容接口](/zh/api-reference/openai/compat-introduction)，可直接使用官方 `openai` SDK。
</Info>