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

> 五档画质的文生图与参考图编辑，Flare 与 Sunburst 两条线路，按 token 用量计费

GPT Image 2.5 是 GPT Image 官方线路的新一代，在 GPT Image 2 的动作和参数之上把画质从三档扩到五档，并对同名档位重新标定了输出用量。它提供 `gpt-image-2.5`（Flare 线）与 `gpt-image-2.5-sunburst`（Sunburst 线）两个模型，请求形状、取值范围和计费方式完全相同，只在出图速度与编辑精度之间取舍，选型只改 `model` 字段。

## 可用模型

| 模型 ID                    | 取舍                | 适合                | 计费           |
| ------------------------ | ----------------- | ----------------- | ------------ |
| `gpt-image-2.5`          | Flare 线，出图更快      | 日常高质量出图、批量生成、快速试稿 | 按实际 token 用量 |
| `gpt-image-2.5-sunburst` | Sunburst 线，编辑精度优先 | 成品素材、广告创意、多轮细节修改  | 按实际 token 用量 |

<Note>
  两个模型的单价相同，同一组参数的花费也相同，差别只在生成结果本身。模型之间不会自动切换。
</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: image25-demo-001" \
    -d '{
      "model": "gpt-image-2.5",
      "action": "generate",
      "prompt": "手工青瓷茶杯放在原色亚麻布上，单侧北向自然光，柔和过渡，静物摄影",
      "aspect_ratio": "1:1",
      "resolution": "1k",
      "quality": "medium",
      "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: image25-edit-001" \
    -d '{
      "model": "gpt-image-2.5-sunburst",
      "action": "edit",
      "prompt": "保留产品与包装文字，把背景换成柔和的米白影棚底，并补一层自然阴影",
      "image_urls": ["https://cdn.example.com/source.png"],
      "aspect_ratio": "1:1",
      "resolution": "2k",
      "quality": "xhigh",
      "n": 1
    }'
  ```
</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.5` 或 `gpt-image-2.5-sunburst`。
</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="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`、`xhigh` 或 `max`。`xhigh` 与 `max` 是 2.5 独有的档位，发给 `gpt-image-2` 会返回 `400`，不会自动降档。画质是这条线路影响成本最大的参数，见下方「计费」。
</ParamField>

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

<ParamField body="background" type="string">
  `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="low">
  内容审核强度：`auto` 或 `low`。
</ParamField>

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

本组不接受 `mask_url` 与 `seed`——掩码局部重绘请用 [`gpt-image-2`](/cn/api-reference/image/gpt-image/gpt-image-2)。以上之外的参数会返回 `400`，不计费。

## 限制

| 条件                          | 限制                                     |
| --------------------------- | -------------------------------------- |
| 每次请求                        | 返回 1 张图                                |
| `action: "edit"`            | 必须提供至少一张参考图                            |
| `background: "transparent"` | `output_format` 只能是 `png` 或 `webp`     |
| 使用 `output_compression`     | `output_format` 必须显式设为 `jpeg` 或 `webp` |
| 参考图张数                       | 最多 16 张                                |
| `xhigh` / `max` 画质          | 只有 2.5 的两个模型接受                         |

## 计费

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

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

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

### 冻结与结算

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

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

画质带来的差距很大。同一画幅、同一分辨率下，预计输出 token 大致是这样一条阶梯：`medium` 约为 `low` 的 2 倍，`high` 约 9 倍，`xhigh` 约 16 倍，`max` 约 36 倍。分辨率再叠一层：`4k` 比 `1k` 高数倍。两者叠加后单张成本可以相差两个数量级。画幅也有影响：同一画质下，`16:9` 的输出 token 低于 `1:1`。

<Note>
  同名档位与上一代不通用：2.5 的 `medium` 与 `high` 输出 token 约为 GPT Image 2 同名档位的四分之一，2.5 的 `max` 才对应 GPT Image 2 的 `high`。从 `gpt-image-2` 迁过来时按本页的阶梯重新估算，不要沿用旧档位的成本预期。
</Note>

各画幅 / 分辨率 / 画质组合的预估输出 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.5",
  "action": "generate",
  "status": "completed",
  "progress": "100%",
  "result": {
    "images": [
      {
        "url": ["https://cdn.example.com/result.png"],
        "expires_at": 1789568757
      }
    ]
  },
  "billing_status": "settled",
  "cost": 6045
}
```

`result.images` 返回生成图片，`expires_at` 是该链接的删除时刻（产物保留 7 天，见[任务状态](/cn/api-reference/task/status)）。任务失败或取消时冻结额度全额退款；如果上游返回成功但没有可交付图片，任务会按失败处理并退款。

## 相关文档

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