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

# GPT-Image 系列

> OpenAI GPT-Image 图像生成 — 多代演进,多比例多分辨率,参考图与遮罩重绘

OpenAI GPT-Image 图像生成模型系列,涵盖加速渠道与官方渠道四个模型:

* **GPT-Image-2** — 加速渠道,15 种比例 × 1K/2K/4K 三档分辨率,按分辨率档计费,性价比最高;仅支持文生图,可一键 `official_fallback` 回退官方渠道
* **GPT-Image-2-Official** — 官方渠道,15 种比例 × 1K/2K/4K 三档,按 **比例 + 分辨率** 精细计价,支持图像编辑与遮罩重绘(inpainting)
* **GPT-Image-1.5-Official** — GPT-Image-1 升级版,画质与指令理解显著提升,按比例计价
* **GPT-Image-1-Official** — 集成文本与图像理解的多模态生成模型,适合高质量生成与编辑,按比例计价

按张计费,支持文生图 / 图像编辑 / 多图参考 / 遮罩重绘(官方渠道)。所有模型 `model` ID 即组名,端点统一为 `POST https://www.qingbo.dev/v1/tasks`。

## 定价

售价单位为美元 / 张。

### GPT-Image-2(按分辨率档)

| 分辨率  | 单价(每张)     |
| ---- | ---------- |
| `1k` | `$0.00675` |
| `2k` | `$0.0135`  |
| `4k` | `$0.02025` |

### GPT-Image-2-Official(按 比例 + 分辨率)

官方渠道按 **每个比例在不同分辨率档** 精细计价,共 15 种比例 × 3 档 = 45 个价位。下表为常用比例示例,其余比例(`4:3` / `3:4` / `5:4` / `4:5` / `2:1` / `1:2` / `3:1` / `1:3` / `9:21`)同样遵循 比例 + 分辨率 的组合定价。

| 比例     | `1k`       | `2k`       | `4k`       |
| ------ | ---------- | ---------- | ---------- |
| `1:1`  | `$0.00549` | `$0.01089` | `$0.01791` |
| `16:9` | `$0.00342` | `$0.00441` | `$0.01017` |
| `9:16` | `$0.00342` | `$0.00441` | `$0.01017` |
| `2:3`  | `$0.00441` | `$0.00585` | `$0.01224` |
| `3:2`  | `$0.00441` | `$0.00585` | `$0.01224` |

### GPT-Image-1.5-Official / GPT-Image-1-Official(按比例)

| 比例    | `gpt-image-1.5-official` | `gpt-image-1-official` |
| ----- | ------------------------ | ---------------------- |
| `1:1` | `$0.09576`               | `$0.12024`             |
| `2:3` | `$0.144`                 | `$0.18`                |
| `3:2` | `$0.144`                 | `$0.18`                |

## 模式速查

| 模式             | 触发字段                                | 支持模型                                                                       |
| -------------- | ----------------------------------- | -------------------------------------------------------------------------- |
| **文生图**        | 仅 `prompt`,`action: "generate"`(默认) | 全部                                                                         |
| **图像编辑 / 图生图** | `+ image_urls` + `action: "edit"`   | `gpt-image-2-official` / `gpt-image-1.5-official` / `gpt-image-1-official` |
| **多图参考**       | `+ image_urls`(多张)                  | 支持 edit 的官方模型(最多 16 张)                                                     |
| **局部重绘(mask)** | `+ image_urls` + `mask_url`         | `gpt-image-2-official`                                                     |

<Note>
  `gpt-image-2`(加速渠道)仅支持 `generate` 文生图;若需要图像编辑、多图融合或遮罩重绘,请使用 `gpt-image-2-official`,或在 `gpt-image-2` 上设 `official_fallback: true` 回退官方渠道。
</Note>

## 调用示例

<CodeGroup>
  ```bash 文生图(最简) theme={"system"}
  curl -X POST https://www.qingbo.dev/v1/tasks \
    -H "Authorization: Bearer $WAVE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-image-2",
      "prompt": "未来主义城市夜景,霓虹灯映在湿润街面,电影感构图",
      "aspect_ratio": "16:9",
      "resolution": "2k"
    }'
  ```

  ```bash 4K 壁纸 theme={"system"}
  curl -X POST https://www.qingbo.dev/v1/tasks \
    -H "Authorization: Bearer $WAVE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-image-2",
      "prompt": "雪山日出全景,自然光,超高清",
      "aspect_ratio": "16:9",
      "resolution": "4k"
    }'
  ```

  ```bash 图像编辑(官方渠道) theme={"system"}
  curl -X POST https://www.qingbo.dev/v1/tasks \
    -H "Authorization: Bearer $WAVE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-image-2-official",
      "action": "edit",
      "prompt": "把背景换成黄昏天空,人物保持不变",
      "image_urls": ["https://cdn.example.com/portrait.jpg"],
      "aspect_ratio": "1:1",
      "resolution": "2k",
      "quality": "high"
    }'
  ```

  ```bash 局部重绘(mask,官方渠道) theme={"system"}
  curl -X POST https://www.qingbo.dev/v1/tasks \
    -H "Authorization: Bearer $WAVE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-image-2-official",
      "action": "edit",
      "prompt": "把遮罩区域替换为蓝色花朵",
      "image_urls": ["https://cdn.example.com/scene.jpg"],
      "mask_url": "https://cdn.example.com/mask.png",
      "aspect_ratio": "1:1",
      "resolution": "2k"
    }'
  ```

  ```bash 透明背景输出(加速渠道) theme={"system"}
  curl -X POST https://www.qingbo.dev/v1/tasks \
    -H "Authorization: Bearer $WAVE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-image-2",
      "prompt": "悬浮的水晶球,产品级摄影,无背景",
      "aspect_ratio": "1:1",
      "resolution": "2k"
    }'
  ```
</CodeGroup>

<Note>
  透明背景:`gpt-image-2-official` / `gpt-image-1.5-official` / `gpt-image-1-official` 官方渠道均不支持 `background: transparent`,设置后系统会静默降级为 `auto`。
</Note>

<ResponseExample>
  ```json 提交成功 theme={"system"}
  {
    "task_id": "task-wave1775285160b950328499",
    "model": "gpt-image-2",
    "action": "generate",
    "status": "queued",
    "created_at": 1775285160040,
    "progress": 0
  }
  ```
</ResponseExample>

提交后用 [`GET /v1/tasks/{task_id}`](/cn/api-reference/task/status) 轮询状态,详见 [任务系统](/cn/docs/task-system)。

## 可用模型

| 模型 ID                    | 渠道 | action              | 说明                                                           |
| ------------------------ | -- | ------------------- | ------------------------------------------------------------ |
| `gpt-image-2`            | 加速 | `generate`          | 15 种比例 × 1K/2K/4K 三档,按分辨率计费,性价比最高;可 `official_fallback` 回退官方 |
| `gpt-image-2-official`   | 官方 | `generate` / `edit` | 15 种比例 × 1K/2K/4K,按比例+分辨率精细计价,支持遮罩重绘                         |
| `gpt-image-1.5-official` | 官方 | `generate` / `edit` | GPT-Image-1 升级版,画质与指令理解显著提升,按比例计费                            |
| `gpt-image-1-official`   | 官方 | `generate` / `edit` | 多模态文本+图像理解,适合高质量生成与编辑,按比例计费                                  |

## 通用参数

<ParamField body="model" type="string" required>
  从 [可用模型](#可用模型) 列表中选一个
</ParamField>

<ParamField body="action" type="string" default="generate">
  操作类型:

  * `generate` — 文生图(默认,全部模型支持)
  * `edit` — 图像编辑 / 图生图 / 多图参考(需配合 `image_urls`,仅官方渠道模型支持)

  `gpt-image-2` 加速渠道仅支持 `generate`。
</ParamField>

<ParamField body="prompt" type="string" required>
  图像描述文本,支持中英文
</ParamField>

<ParamField body="n" type="integer" default="1">
  生成数量,范围 `1 ~ 4`
</ParamField>

<ParamField body="seed" type="integer">
  随机种子,固定值可复现相似结果(仅 `gpt-image-2` / `gpt-image-2-official` 支持)
</ParamField>

<ParamField body="aspect_ratio" type="string" default="1:1">
  画面宽高比,**取值取决于模型**:

  * GPT-Image-2 / GPT-Image-2-Official:`1:1` / `3:2` / `2:3` / `4:3` / `3:4` / `5:4` / `4:5` / `16:9` / `9:16` / `2:1` / `1:2` / `3:1` / `1:3` / `21:9` / `9:21`(共 15 种)
  * GPT-Image-1.5-Official / GPT-Image-1-Official:`1:1` / `3:2` / `2:3`(仅 3 种)
</ParamField>

<ParamField body="resolution" type="string" default="1k">
  输出分辨率档,**仅 GPT-Image-2 / GPT-Image-2-Official 支持**:

  * `1k` — 1K 档(默认,1024 基线)
  * `2k` — 2K 档(2048 基线,海报 / 高清场景)
  * `4k` — 4K 档(3840 基线)

  GPT-Image-1.5 / 1 official 不接收该字段,沿用模型默认。
</ParamField>

<ParamField body="image_urls" type="string[]">
  参考图片 URL 数组,**最多 16 张**;同时支持 base64 直传。仅官方渠道(`edit`)使用
</ParamField>

<ParamField body="callback_url" type="string">
  Webhook 回调地址,任务终态时调用。详见 [回调机制](/cn/docs/sync-async#异步任务-webhook)
</ParamField>

<ParamField body="callback_events" type="string[]">
  回调事件过滤,如 `["completed", "failed"]`
</ParamField>

## 模型特定参数

<Tabs>
  <Tab title="GPT-Image-2">
    **支持 action**:`generate`(仅文生图)

    **aspect\_ratio**(15 种):`1:1` / `3:2` / `2:3` / `4:3` / `3:4` / `5:4` / `4:5` / `16:9` / `9:16` / `2:1` / `1:2` / `3:1` / `1:3` / `21:9` / `9:21`

    **resolution**:`1k` / `2k` / `4k`

    **核心特性**:加速渠道,按分辨率档计费,性价比最高;参考图最多 16 张(URL / base64)

    <ParamField body="official_fallback" type="boolean" default="false">
      置为 `true` 时回退到 `gpt-image-2-official` 官方渠道(可获得编辑 / 遮罩等官方能力)
    </ParamField>
  </Tab>

  <Tab title="GPT-Image-2-Official">
    **支持 action**:`generate` / `edit`

    **aspect\_ratio**(15 种):`1:1` / `3:2` / `2:3` / `4:3` / `3:4` / `5:4` / `4:5` / `16:9` / `9:16` / `2:1` / `1:2` / `3:1` / `1:3` / `21:9` / `9:21`

    **resolution**:`1k` / `2k` / `4k`

    **核心特性**:官方渠道,按 比例 + 分辨率 精细计价,支持图像编辑、多图参考与遮罩重绘;参考图最多 16 张

    <ParamField body="quality" type="string" default="auto">
      生成质量,可选值:

      * `auto` — 自动(默认)
      * `low` — 低质量
      * `medium` — 中等质量
      * `high` — 高质量(`4k + high` 可能 >120s)
    </ParamField>

    <ParamField body="mask_url" type="string">
      inpainting 遮罩图 URL,局部重绘(配合 `image_urls`,需含 Alpha 通道且与首张参考图同尺寸)
    </ParamField>

    <ParamField body="background" type="string" default="auto">
      背景处理,可选值:

      * `auto` — 自动(默认)
      * `opaque` — 不透明
      * `transparent` — 官方渠道不支持,设置后静默降级为 `auto`
    </ParamField>

    <ParamField body="moderation" type="string" default="auto">
      内容审核级别,可选值:`auto`(默认) / `low`(更宽松)
    </ParamField>

    <ParamField body="output_format" type="string" default="png">
      输出格式,可选值:

      * `png` — 默认
      * `jpeg`
      * `webp`
    </ParamField>

    <ParamField body="output_compression" type="integer">
      输出压缩率,范围 0-100,**仅 `jpeg` / `webp` 生效**
    </ParamField>
  </Tab>

  <Tab title="GPT-Image-1.5-Official">
    **支持 action**:`generate` / `edit`

    **aspect\_ratio**(3 种):`1:1` / `3:2` / `2:3`

    **resolution**:不接收(沿用默认)

    **核心特性**:GPT-Image-1 升级版,画质和指令理解显著提升,按比例计费

    <ParamField body="quality" type="string" default="auto">
      生成质量,可选值:`auto` / `low` / `medium` / `high`
    </ParamField>

    <ParamField body="background" type="string" default="auto">
      背景处理,可选值:`auto` / `opaque` / `transparent`(官方渠道不支持 transparent)
    </ParamField>

    <ParamField body="moderation" type="string" default="auto">
      内容审核级别,可选值:`auto` / `low`
    </ParamField>

    <ParamField body="output_format" type="string" default="png">
      输出格式,可选值:

      * `png` — 默认
      * `jpeg`
    </ParamField>

    <ParamField body="output_compression" type="integer">
      输出压缩率,范围 0-100,**仅 `jpeg` 生效**
    </ParamField>
  </Tab>

  <Tab title="GPT-Image-1-Official">
    **支持 action**:`generate` / `edit`

    **aspect\_ratio**(3 种):`1:1` / `3:2` / `2:3`

    **resolution**:不接收(沿用默认)

    **核心特性**:集成文本和图像理解的多模态生成模型,适合高质量生成与编辑,按比例计费

    <ParamField body="quality" type="string" default="auto">
      生成质量,可选值:`auto` / `low` / `medium` / `high`
    </ParamField>

    <ParamField body="background" type="string" default="auto">
      背景处理,可选值:`auto` / `opaque` / `transparent`(官方渠道不支持 transparent)
    </ParamField>

    <ParamField body="moderation" type="string" default="auto">
      内容审核级别,可选值:`auto` / `low`
    </ParamField>

    <ParamField body="output_format" type="string" default="png">
      输出格式,可选值:

      * `png` — 默认
      * `jpeg`
    </ParamField>

    <ParamField body="output_compression" type="integer">
      输出压缩率,范围 0-100,**仅 `jpeg` 生效**
    </ParamField>
  </Tab>
</Tabs>

## 资源限制

| 项目     | 限制                                                      |
| ------ | ------------------------------------------------------- |
| 单次生成张数 | `n` 范围 1 \~ 4                                           |
| 参考图片张数 | 最多 16 张(URL 或 base64)                                   |
| 单图大小   | ≤ 20MB / 张,总计 ≤ 256MB                                   |
| 输出分辨率  | GPT-Image-2 / 2-Official 最高 4K;1.5 / 1 official 沿用默认    |
| 输出格式   | PNG(默认)/ JPEG / WEBP(仅 GPT-Image-2-Official),链接 24 小时有效 |
| 透明背景   | 仅 `gpt-image-2` 加速渠道支持;官方渠道静默降级为 `auto`                 |

## 相关文档

* [任务系统详解](/cn/docs/task-system) — 任务状态机 / 轮询节奏 / 异步推送
* [请求响应格式](/cn/docs/request-response) — 通用错误码 / Headers / 限流
* [认证](/cn/docs/authentication) — API Key 申请与使用