> ## 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 2 官方版

> 文生图、参考图编辑与掩码局部重绘，按 token 用量计费

`gpt-image-2` 是 GPT Image 2 的官方 API 线路，适合产品图、海报、插画和基于参考图的视觉编辑。所有操作都通过统一任务接口 `POST /v1/tasks` 提交。

<Note>
  需要按固定张价调用时，可使用 [`gpt-image-2-rev`](/cn/api-reference/image/gpt-image/gpt-image-2-rev)。两条线路使用相同的任务接口，但模型 ID、参数和计费方式不同，不会自动互相切换。
</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" \
    -H "Idempotency-Key: image-demo-001" \
    -d '{
      "model": "gpt-image-2",
      "action": "generate",
      "prompt": "一只蓝色陶瓷杯放在白色桌面上，柔和自然光，产品摄影",
      "aspect_ratio": "1:1",
      "resolution": "1k",
      "quality": "low",
      "n": 1
    }'
  ```

  ```bash 参考图编辑 theme={"system"}
  curl -X POST https://www.qingbo.dev/v1/tasks \
    -H "Authorization: Bearer $WAVE_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: image-edit-001" \
    -d '{
      "model": "gpt-image-2",
      "action": "edit",
      "prompt": "保留主体，把背景改成日落时的海边",
      "image_urls": ["https://cdn.example.com/source.png"],
      "aspect_ratio": "1:1",
      "resolution": "1k",
      "quality": "low",
      "n": 1
    }'
  ```

  ```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",
      "action": "edit",
      "prompt": "只把杯子改成深绿色，其余区域保持不变",
      "image_urls": ["https://cdn.example.com/source.png"],
      "mask_url": "https://cdn.example.com/mask.png",
      "resolution": "1k",
      "quality": "medium"
    }'
  ```
</CodeGroup>

提交成功后返回 `task_id`。用 [`GET /v1/tasks/{task_id}`](/cn/api-reference/task/status) 查询结果，也可以用 [`Prefer: wait`](/cn/api-reference/task/submit#请求内等待prefer-wait) 在一次调用里等待，或配置 Webhook。

## 请求参数

<ParamField body="model" type="string" required>
  固定为 `gpt-image-2`。
</ParamField>

<ParamField body="action" type="string" default="generate">
  * `generate`：根据文字生成图片
  * `edit`：编辑参考图；必须提供 `image_urls`
</ParamField>

<ParamField body="prompt" type="string" required>
  图片描述或编辑指令。
</ParamField>

<ParamField body="image_urls" type="string[]">
  参考图片 URL。`edit` 时必填，最多 16 张。
</ParamField>

<ParamField body="mask_url" type="string">
  局部重绘掩码 URL。必须同时提供 `image_urls`，并与第一张参考图尺寸一致。
</ParamField>

<ParamField body="aspect_ratio" type="string" default="1:1">
  支持 `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`。
</ParamField>

<ParamField body="resolution" type="string" default="1k">
  输出分辨率：`1k`、`2k` 或 `4k`。
</ParamField>

<ParamField body="quality" type="string" default="low">
  画质档位：`low`、`medium` 或 `high`。画质越高，生成成本通常越高。
</ParamField>

<ParamField body="n" type="integer" default="1">
  生成数量，取值 `1`。每次请求返回一张图。
</ParamField>

<ParamField body="background" type="string" default="auto">
  `auto`、`opaque` 或 `transparent`。透明背景只支持 `png` 和 `webp`。
</ParamField>

<ParamField body="output_format" type="string" default="png">
  `png`、`jpeg` 或 `webp`。
</ParamField>

<ParamField body="output_compression" type="integer">
  JPEG/WebP 压缩比例，范围 `0`–`100`。使用时必须将 `output_format` 设为 `jpeg` 或 `webp`。
</ParamField>

<ParamField body="moderation" type="string" default="auto">
  内容审核强度：`auto` 或 `low`。
</ParamField>

通用的 `callback_url`、`callback_events`、`Prefer: wait`、`Idempotency-Key` 和费用上限请求头见[提交任务](/cn/api-reference/task/submit)。

官方线路不支持 `seed`。以上之外的参数会返回 `400`，不计费。

## 限制

| 条件                          | 限制                                     |
| --------------------------- | -------------------------------------- |
| 每次请求                        | 返回 1 张图                                |
| `action: "edit"`            | 必须提供至少一张参考图                            |
| 使用 `mask_url`               | 必须同时提供 `image_urls`，且掩码与第一张参考图尺寸一致     |
| `background: "transparent"` | `output_format` 只能是 `png` 或 `webp`     |
| 使用 `output_compression`     | `output_format` 必须显式设为 `jpeg` 或 `webp` |
| 参考图张数                       | 最多 16 张                                |

## 计费

官方线路**按实际 token 用量计费**，共五个计费维度：文本输入、缓存文本输入、图片输入、缓存图片输入、图片输出。

单价见 `GET /v1/models` 返回的 `price_config`，或控制台「模型市场」。单次调用的实际花费见任务响应里的 `cost`——整数 quota，**500,000 quota = 1 USD**，不是美元。

图片输入包括参考图和掩码。缓存费率仅在上游返回可用于结算的缓存用量时生效；没有缓存用量时只按普通输入和图片输出计费。

### 冻结与结算

提交任务时按预估用量冻结一笔额度，任务完成后按实际用量结算，差额退回。预估用量的算法是：

* **输出**：按画幅、分辨率和画质三项查表得到预计输出 token 数
* **文本输入**：不足 32 token 按 32 计
* **参考图**：每张按 4,096 token 计，掩码同样算作图片输入

输出 token 的量级差异很大：同一画幅下，`high` 档的预计输出 token 约是 `low` 档的 **36 倍**，`4k` 又比 `1k` 高数倍，两者叠加后单张成本可以相差两个数量级。`quality` 是这条线路影响成本最大的参数，默认值为 `low`。画幅同样有影响：同一画质下，`16:9` 的输出 token 低于 `1:1`。

各画幅 / 分辨率 / 画质组合的预估输出 token，见公开模型详情 `GET /v1/models` 的 `price_config.image_usage_reservation`。

只有成功出图才计费。任务失败、取消，或没有返回可用图片时，全额退款。完整字段说明见[任务状态](/cn/api-reference/task/status)。

## 响应

```json 任务完成 theme={"system"}
{
  "task_id": "taski_example",
  "model": "gpt-image-2",
  "action": "edit",
  "status": "completed",
  "progress": "100%",
  "result": {
    "images": [
      {
        "url": ["https://cdn.example.com/result.png"]
      }
    ]
  },
  "billing_status": "settled",
  "cost": 6368
}
```

`result.images` 返回生成图片。任务失败或取消时冻结额度全额退款；如果上游返回成功但没有可交付图片，任务会按失败处理并退款。

## 相关文档

* [GPT Image 系列](/cn/api-reference/image/gpt-image/overview)
* [GPT Image 1 与 1.5 官方版](/cn/api-reference/image/gpt-image/gpt-image-1)
* [GPT Image 2 逆向版](/cn/api-reference/image/gpt-image/gpt-image-2-rev)
* [提交任务](/cn/api-reference/task/submit)
* [查询任务状态](/cn/api-reference/task/status)
* [任务系统](/cn/docs/task-system)