> ## 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 1 与 1.5 官方版
> 文生图、参考图编辑与掩码局部重绘，按 token 用量计费
`gpt-image-1` 和 `gpt-image-1.5` 是 OpenAI 官方 API 线路上的两代图像模型，支持文生图、最多 15 张参考图编辑和掩码局部重绘。两者的动作、参数、取值集合和限制完全一致，切换模型只改 `model` 字段。所有操作都通过统一任务接口 `POST /v1/tasks` 提交。
这两个模型不接受 `resolution`，画幅只有 `1:1`、`2:3` 和 `3:2`。需要分辨率档位、更多画幅或 WebP 输出时使用 [GPT Image 2 官方版](/cn/api-reference/image/gpt-image/gpt-image-2)；需要按固定张价调用时使用 [GPT Image 2 逆向版](/cn/api-reference/image/gpt-image/gpt-image-2-rev)。模型 ID 决定走哪个模型，不会自动切换。
## 快速开始
```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-gi15-001" \
-d '{
"model": "gpt-image-1.5",
"action": "generate",
"prompt": "一只蓝色陶瓷杯放在白色桌面上，柔和自然光，产品摄影",
"aspect_ratio": "1:1",
"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-gi1-edit-001" \
-d '{
"model": "gpt-image-1",
"action": "edit",
"prompt": "保留主体，把背景改成日落时的海边",
"image_urls": ["https://cdn.example.com/source.png"],
"aspect_ratio": "3:2",
"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-1.5",
"action": "edit",
"prompt": "只把杯子改成深绿色，其余区域保持不变",
"image_urls": ["https://cdn.example.com/source.png"],
"mask_url": "https://cdn.example.com/mask.png",
"quality": "medium"
}'
```
提交成功后返回 `task_id`。用 [`GET /v1/tasks/{task_id}`](/cn/api-reference/task/status) 查询结果，也可以用 [`Prefer: wait`](/cn/api-reference/task/submit#请求内等待prefer-wait) 在一次调用里等待，或配置 Webhook。
## 请求参数
`gpt-image-1` 或 `gpt-image-1.5`。
* `generate`：根据文字生成图片
* `edit`：编辑参考图；必须提供 `image_urls`
图片描述或编辑指令。
参考图片 URL。`edit` 时必填，最多 15 张。
局部重绘掩码 URL，仅 `edit` 有效。必须同时提供 `image_urls`，与第一张参考图尺寸一致并包含透明通道。
支持 `1:1`、`2:3` 和 `3:2`。
画质档位：`auto`、`low`、`medium` 或 `high`。`auto` 由模型选档。画质越高，生成成本通常越高。
生成数量，取值 `1`。每次请求返回一张图。
`auto`、`opaque` 或 `transparent`。透明背景只支持 `png`。
`png` 或 `jpeg`。
JPEG 压缩质量，范围 `0`–`100`。使用时必须将 `output_format` 设为 `jpeg`。
内容审核强度：`auto` 或 `low`。
通用的 `callback_url`、`callback_events`、`Prefer: wait`、`Idempotency-Key` 和费用上限请求头见[提交任务](/cn/api-reference/task/submit)。
这两个模型不支持 `resolution` 和 `seed`。以上之外的参数会返回 `400`，不计费。
## 限制
| 条件 | 限制 |
| --------------------------- | ---------------------------------- |
| 每次请求 | 返回 1 张图 |
| `action: "edit"` | 必须提供至少一张参考图 |
| 使用 `mask_url` | 必须同时提供 `image_urls`，且掩码与第一张参考图尺寸一致 |
| `background: "transparent"` | `output_format` 只能是 `png` |
| 使用 `output_compression` | `output_format` 必须显式设为 `jpeg` |
| 参考图张数 | 最多 15 张 |
## 计费
两个模型都**按实际 token 用量计费**。`gpt-image-1` 有五个计费维度：文本输入、缓存文本输入、图片输入、缓存图片输入、图片输出；`gpt-image-1.5` 在这五项之外还计文本输出。
单价见 `GET /v1/models` 返回的 `price_config`，或控制台「模型市场」。单次调用的实际花费见任务响应里的 `cost`——整数 quota，**500,000 quota = 1 USD**，不是美元。
图片输入包括参考图和掩码。缓存费率仅在上游返回可用于结算的缓存用量时生效；没有缓存用量时只按普通输入和图片输出计费。
### 冻结与结算
提交任务时按预估用量冻结一笔额度，任务完成后按实际用量结算，差额退回。预估用量的算法是：
* **输出**：按画幅和画质两项查表得到预计输出 token 数
* **文本输入**：不足 64 token 按 64 计
* **参考图**：每张按 4,096 token 计，掩码同样算作图片输入
* **文本输出**：仅 `gpt-image-1.5` 有这一项，按 1,024 token 计
同一画幅下，`high` 档的预计输出 token 约是 `low` 档的 **15 倍**。`quality` 是影响成本最大的参数，默认值为 `auto`；不传 `quality` 时按 `auto` 计，而 `auto` 与 `high` 的预估口径相同。画幅也有影响：同一画质下，`2:3` 和 `3:2` 的输出 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-1.5",
"action": "generate",
"status": "completed",
"progress": "100%",
"result": {
"images": [
{
"url": ["https://cdn.example.com/result.png"]
}
]
},
"billing_status": "settled",
"cost": 61859
}
```
`result.images` 返回生成图片。任务失败或取消时冻结额度全额退款；如果上游返回成功但没有可交付图片，任务会按失败处理并退款。
## 可用模型
| 模型 ID | 定位 | 计费维度 |
| --------------- | ---------------------------------- | ------------------------------------ |
| `gpt-image-1` | OpenAI 图像生成与编辑模型，支持多图参考、画面内文字和局部重绘 | 文本输入 / 缓存文本输入 / 图片输入 / 缓存图片输入 / 图片输出 |
| `gpt-image-1.5` | OpenAI 上一代高质量图像模型，遵循复杂提示词和画面内文字更稳 | 上述五项，另加文本输出 |
两个模型的动作、参数、取值集合和限制完全一致，本页的每一节对两者都适用。
## 相关文档
* [GPT Image 系列](/cn/api-reference/image/gpt-image/overview)
* [GPT Image 2 官方版](/cn/api-reference/image/gpt-image/gpt-image-2)
* [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)