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

# GPT Image 2.5 API：图像生成与编辑、官转与按次计费

> 用老张API调用 GPT Image 2.5 Flare 与 Sunburst：按次计费与官转按 token 计费的模型 ID、令牌分组和价格，附生成、编辑与透明背景示例。

GPT Image 2.5 是 OpenAI 当前的图像模型，有两款：优先速度选 **Flare**，优先精细编辑选 **Sunburst**。老张API提供官方 API 转发（官转）、VIP 按次和网页版三条线路，先按下表选线路。

<Info>
  `gpt-image-2.5-flare-vip` 和 `gpt-image-2.5-sunburst-vip` 于 2026 年 9 月 16 日停用，9 月 22 日起恢复可用。详见[恢复公告与调用说明](/announcements/gpt-image-2-5-vip-restored-2026-09-22)。
</Info>

## 先选择接入线路

| 线路 | 模型 ID | 令牌分组与计费模式 | 计费 |
| - | - | - | - |
| 官转 | `gpt-image-2.5-flare`、`gpt-image-2.5-sunburst` | `Sora2Official` 或 `GPTImage2 Sora2 Enterprise`，按量优先或按量计费 | 按 token，单价与 `gpt-image-2` 官转相同，见[官转计费](#官转计费) |
| VIP 按次 | `gpt-image-2.5-flare-vip`、`gpt-image-2.5-sunburst-vip` | `default` 或其他图像分组（名称见控制台），按量优先或按次计费 | \$0.03/次 |
| 网页版 | `gpt-image-2.5-web` | `default` 或其他图像分组（名称见控制台），按量优先或按次计费 | \$0.03/次 |

三条线路都用 `/v1/images/generations` 生成、`/v1/images/edits` 编辑。价格来自 2026 年 9 月 24 日公开价格配置，见[模型与价格总表](/models)。已有 GPT Image 2 集成可继续参考 [GPT Image 2 文档](/api-capabilities/gpt-image-2)。

## 价格与能力一览

| 线路 | 生成 | 编辑 |
| - | - | - |
| VIP：`gpt-image-2.5-flare-vip`、`gpt-image-2.5-sunburst-vip` | \$0.03/次 | \$0.03/次 |
| 网页版：`gpt-image-2.5-web` | \$0.03/次 | \$0.03/次 |
| 官转：`gpt-image-2.5-flare`、`gpt-image-2.5-sunburst` | 按 token | 按 token |

价格为 2026 年 9 月 24 日公开价格配置，核对日期 2026 年 10 月 10 日。VIP 与网页版的尺寸、五档质量都不改变单价。模型来自 OpenAI 官方渠道：官转按 OpenAI 官方 token 价计费，按次线路以固定单价计费，高分辨率和高质量档位时低于按 token 计费。

| 能力 | VIP 按次 | 官转 |
| - | - | - |
| 需要 OpenAI 账号 | 不需要，只用老张API密钥 | 不需要 |
| 文生图与图生图编辑 | 都支持，同价 | 都支持，按 token |
| 透明背景 PNG | 支持，`background="transparent"` + `output_format="png"` | 支持，参数同 OpenAI |
| 参考图 | 支持上传图片编辑，不支持 `mask` | 最多 16 张，支持 `mask` |
| 尺寸与质量 | 自定义宽高，单边最大 3840；`low` 到 `max` 五档同价 | OpenAI 官方尺寸与质量档位 |
| 协议 | OpenAI Images API：`/v1/images/generations`、`/v1/images/edits` | 同左 |
| 并发 | 平台不限制，`429` 来自上游容量，见[并发与 429](/faq/api-concurrency) | 同左 |
| 失败扣费 | 返回错误、未生成图片一般不扣费，见[扣费与失败规则](/api-capabilities/image-billing-and-failures) | 同左 |

## 官转模型与分组

| 请求中的模型 ID | 当前指向 | 选择建议 |
| - | - | - |
| `gpt-image-2.5-flare` | `gpt-image-2.5-flare-2026-09-08` | 更快的日常高质量生成 |
| `gpt-image-2.5-sunburst` | `gpt-image-2.5-sunburst-2026-09-08` | 更注重编辑精度的生成与图改图 |

一般接入使用不带日期的别名；需要固定版本时，使用表中的完整快照 ID。别名的当前映射今后可能变化。

1. 在[令牌管理](https://api.laozhang.ai/token)创建令牌，计费模式选择「按量优先」（推荐）或「按量计费」，并确认令牌允许调用目标模型。
2. 分组选择官转分组，分组只在创建令牌时选择，不填入请求的 `model`：
   * `Sora2Official`：与 OpenAI 官方同价，上游为 Azure OpenAI 与 OpenAI 官方密钥混合。
   * `GPTImage2 Sora2 Enterprise`（企业官转）：只使用 OpenAI 官方密钥，为官方价加 20%，适合优先稳定性的生产调用。
3. 保留原有官转 Images API 的鉴权、请求结构和结果处理，只把 `model` 改为上述别名或快照 ID。

## 官转最小接入

以下示例分别调用官转的文生图和图像编辑接口，在 SDK 中对应 `images.generate` 与 `images.edit`。先设置官转令牌，并安装保存脚本需要的 `pillow`：

```bash theme={null}
export LAOZHANG_API_KEY="替换为你的官转分组令牌"
export BASE_URL="https://api.laozhang.ai/v1"
python -m pip install pillow
```

### Flare 文生图

```bash theme={null}
curl --fail-with-body "$BASE_URL/images/generations" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "白色陶瓷杯的产品照片，灰色桌面，柔和自然光",
    "size": "1024x1024",
    "quality": "medium"
  }' -o generation.json
```

### Sunburst 图像编辑

先准备本地 `source.png`，再运行：

```bash theme={null}
curl --fail-with-body "$BASE_URL/images/edits" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -F "model=gpt-image-2.5-sunburst" \
  -F "image=@source.png" \
  -F "prompt=保留杯子的形状、构图和光照，只将杯身改为深蓝色。" \
  -F "size=1024x1024" \
  -F "quality=medium" \
  -o edit.json
```

两款模型都接受文本与图像输入。示例按各自侧重点选型，并不表示 Flare 不能编辑或 Sunburst 不能生成。

官转参数参考 [OpenAI 图像生成指南](https://developers.openai.com/api/docs/guides/image-generation)；按次模型的质量选项见下文「尺寸与质量」，两种线路的参数范围不要混用。

### 保存图片与查看结果

响应的 `data[]` 中，每一项是下面两种之一：

* `b64_json`：Base64 图片内容，可能带 `data:image/png;base64,` 这类前缀，也可能缺少末尾的 `=`。
* `url`：图片下载地址，会过期，收到响应后要尽快下载。

将以下代码保存为 `save_images.py`，它会处理上述情况，并按实际格式命名文件：

```python theme={null}
import base64
import io
import json
import sys
import urllib.request
from pathlib import Path
from PIL import Image

if len(sys.argv) != 3:
    raise SystemExit("用法：python save_images.py 响应文件.json 输出文件前缀")


def decode_b64(value):
    # 去掉可能存在的 data:image/...;base64, 前缀，并补齐缺失的 = 填充
    if value.startswith("data:"):
        value = value.split(",", 1)[1]
    value = "".join(value.split())
    value += "=" * (-len(value) % 4)
    return base64.b64decode(value, validate=True)


response_path = Path(sys.argv[1])
output_prefix = sys.argv[2]
payload = json.loads(response_path.read_text(encoding="utf-8"))
if payload.get("error"):
    raise RuntimeError(payload["error"])
items = payload.get("data") or []
if not items:
    raise RuntimeError("响应中没有图片结果，请检查错误信息和调用日志")

for index, item in enumerate(items, start=1):
    if item.get("b64_json"):
        raw = decode_b64(item["b64_json"])
    elif item.get("url"):
        with urllib.request.urlopen(item["url"], timeout=60) as download:
            raw = download.read()
    else:
        raise RuntimeError(f"第 {index} 项缺少图片内容或下载地址")

    with Image.open(io.BytesIO(raw)) as picture:
        picture.load()
        extension = {"PNG": "png", "JPEG": "jpg", "WEBP": "webp"}.get(
            picture.format
        )
        if extension is None:
            raise RuntimeError(f"无法保存图片格式：{picture.format}")
        output = Path(f"{output_prefix}-{index}.{extension}")
        output.write_bytes(raw)
        print(f"已保存 {output}，尺寸 {picture.width} × {picture.height}")
```

生成或编辑请求结束后分别执行：

```bash theme={null}
python save_images.py generation.json generated
python save_images.py edit.json edited
```

打开保存的图片，检查能否正常显示、打印出的尺寸是否符合请求；编辑时再检查要求保留的内容和指定的改动。随后在[控制台调用日志](https://api.laozhang.ai/log)核对模型、分组、usage 和实际扣费。

认证或模型权限错误时，先检查 Key、分组和模型 ID；参数错误按返回信息调整请求。若响应里没有图片，保留脱敏后的错误信息和请求时间，按 [Images API 参考](/api-reference/images)排查；联系支持时不要发送完整 Key。

## 官转计费

两款官转模型按量计费，与 `gpt-image-2` 官转的 token 单价相同，按文本输入、图片输入和图片输出的实际用量扣费。2026 年 9 月 24 日公开价格配置中，`Sora2Official` 分组的单价如下，与 OpenAI 官方价格相同：

| 计费项 | 每 1M tokens 单价（美元） |
| - | - |
| 文本输入 | \$5 |
| 缓存文本输入 | \$1.25 |
| 图片输入 | \$8 |
| 缓存图片输入 | \$2 |
| 图片输出 | \$30 |

`GPTImage2 Sora2 Enterprise` 分组在此基础上加 20%（分组倍率 1.2），例如图片输出为每 1M tokens \$36。当前价格以[模型与价格总表](/models)和[控制台](https://api.laozhang.ai/account/pricing)为准，企业报价联系支持团队确认。

token 单价相同不等于每张图片的总价相同：模型、尺寸、质量和参考图都会影响 token 用量，应以代表性请求的 usage 估算。token 的计算方式见 [OpenAI 图像生成指南的成本说明](https://developers.openai.com/api/docs/guides/image-generation#cost-and-latency)。

## VIP 按次计费接入

两款 VIP 模型按次计费，接入方式与 `gpt-image-2-vip` 相同：使用 `default`（默认分组）或其他图像分组（名称见控制台）中计费模式为「按量优先」（推荐）或「按次计费」的令牌。

调用时必须保留模型名中的 `-vip` 后缀；不带后缀的 Flare / Sunburst 走官转，按 token 计费。本节的参数和示例只适用于这两款 `-vip` 模型，不能直接套用到 `gpt-image-2.5-web`。

### 尺寸与质量

两款 VIP 模型的文生图请求都可以使用 `size` 和 `quality`。不需要指定尺寸或质量时，省略相应字段即可。

| 参数 | 写法 | 使用说明 |
| - | - | - |
| `size` | `宽x高`，例如 `2048x2048` | 常规尺寸均支持，也可填写符合下述限制的自定义宽高 |
| `quality` | `low` / `medium` / `high` / `xhigh` / `max` | 两款模型均支持这五档，可按任务选择，或把五档都提供给用户 |

常规尺寸覆盖 1K、2K、4K 及常见的方图、横图和竖图画幅，也可以使用合法范围内的自定义宽高，例如 `1440x960`、`1536x864` 或 `2048x1152`。自定义尺寸需同时满足：

* 宽、高均为 **16 的整数倍**；
* 任一边不超过 **3840 像素**；
* 长边与短边之比不超过 **3:1**；
* 总像素数（宽 × 高）在 **655,360 到 8,294,400** 之间。

尺寸格式与边界参考 [OpenAI 图像生成指南](https://developers.openai.com/api/docs/guides/image-generation)。工作台的下拉框只列常用预设，直接调用 API 时可以填写符合上述条件的自定义 `size`。

下表是常用尺寸示例，不是完整列表：

| 常用示例 | `size` | 画幅 |
| - | - | - |
| 1K 方图 | `1024x1024` | 1:1 |
| 横图 | `1536x1024` | 3:2 |
| 竖图 | `1024x1536` | 2:3 |
| 2K 方图 | `2048x2048` | 1:1 |
| 4K 横图 | `3840x2160` | 16:9 |
| 4K 竖图 | `2160x3840` | 9:16 |

不符合上述条件的尺寸可能被自动调整，例如 `1023x1024` 可能返回 `1024x1024`。需要精确像素时，使用符合条件的尺寸，并检查返回图片的实际宽高。

入门请求可以先用 `size="2048x2048"`、`quality="medium"`。

### 文生图示例

已有 `gpt-image-2-vip` 集成时，保留 base URL、鉴权、接口和结果处理，把 `model` 换成完整的 `-vip` 模型 ID。以下示例生成一张 2K 方图：

```bash theme={null}
export LAOZHANG_API_KEY="替换为你的 default 分组令牌"

curl --fail-with-body "https://api.laozhang.ai/v1/images/generations" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare-vip",
    "prompt": "白色陶瓷杯的产品照片，灰色桌面，柔和自然光",
    "size": "2048x2048",
    "quality": "medium"
  }' -o generation.json
```

### 图像编辑示例

编辑使用 `/v1/images/edits` 和 multipart 请求。先准备本地 `source.png`，上传图片并描述需要修改的内容：

```bash theme={null}
curl --fail-with-body "https://api.laozhang.ai/v1/images/edits" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -F "model=gpt-image-2.5-sunburst-vip" \
  -F "image=@source.png" \
  -F "prompt=保留杯子的形状、构图和光照，只将杯身改为深蓝色。" \
  -o edit.json
```

两个示例中的模型 ID 可以互换。结果用上文的 `save_images.py` 保存。

### 透明背景 PNG

两款 VIP 模型都支持**生成透明背景 PNG**，也支持上传图片后**去除背景、保留主体**。在请求中设置：

```json theme={null}
{
  "background": "transparent",
  "output_format": "png"
}
```

生成请求使用 JSON；编辑请求使用 multipart，把这两个参数作为表单字段传入。以下示例使用 `1024x1024` 和 `medium`。

#### 生成透明背景图片

```bash theme={null}
curl --fail-with-body "https://api.laozhang.ai/v1/images/generations" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare-vip",
    "prompt": "一只带银色瓶盖的蓝色玻璃香水瓶，居中摆放，轮廓清晰，主体四周留空，不要文字、水印或棋盘格。",
    "size": "1024x1024",
    "quality": "medium",
    "background": "transparent",
    "output_format": "png"
  }' -o generation.json
```

#### 上传图片并去除背景

先准备本地 `source.png`，再上传原图并描述需要保留的主体：

```bash theme={null}
curl --fail-with-body "https://api.laozhang.ai/v1/images/edits" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -F "model=gpt-image-2.5-sunburst-vip" \
  -F "image=@source.png" \
  -F "prompt=移除整个背景，只保留杯子及其标签，保留杯子的形状、颜色和文字，不要桌面、墙壁或主体之外的阴影。" \
  -F "size=1024x1024" \
  -F "quality=medium" \
  -F "background=transparent" \
  -F "output_format=png" \
  -o edit.json
```

两个示例中的模型 ID 可以互换。用 `save_images.py` 保存后得到 PNG 文件，alpha 通道保留透明区域，可以直接叠放到其他底色上。不要转存为 JPEG，否则会丢失透明效果。

<Note>
  透明背景与 `mask` 局部编辑是不同功能。这两款按次模型不支持通过 `mask` 限定修改区域；去背景时使用上面的 `background="transparent"` 参数和保留主体的提示词即可。
</Note>

## 网页版线路

网页版 2.5 的模型 ID 是 `gpt-image-2.5-web`，这条线路：

* 按次计费；
* 支持生成（`/v1/images/generations`）和编辑（`/v1/images/edits`），支持 `size`；
* 不能指定 Flare / Sunburst，稳定性与参数以控制台和调用结果为准。

需要固定使用 Flare 或 Sunburst 时，选择对应的官转模型或 `-vip` 模型，各线路的尺寸与质量参数见上文。

`gpt-image-2-web` 是已有集成使用的历史网页版 ID，与 `gpt-image-2.5-web` 不是同一路由，参数也不能混用。当前令牌权限和实际输出以[控制台](https://api.laozhang.ai/account/pricing)及调用结果为准。

## 常见问题

### Flare 和 Sunburst 同价吗？怎么选？

价格相同：官转的两款模型使用同一组 token 单价（见[官转计费](#官转计费)），两款 `-vip` 模型的单次价格也一样。选择只看效果：日常生成、在意出图速度选 Flare，改图时更看重保留原图细节选 Sunburst。两款都能生成和编辑，也可以都提供给用户挑选。

### 换到 2.5 后 quality 能照旧填吗？

可以照旧填 `low`、`medium`、`high`，但同名档位在两代模型上消耗的输出 token 可能不一样。按 OpenAI 的说明，两代模型的图片输出 token 单价相同，同一质量设置用到的 token 数却可能不同。

所以从 `gpt-image-2` 换过来后，要用自己的提示词重新测官转的费用和耗时，对照响应里的 `usage` 或[调用日志](https://api.laozhang.ai/log)。

2.5 还新增了 `xhigh` 和 `max` 两档，上一代最高只到 `high`。VIP 模型按次计费，五档价格相同，档位只影响细节和耗时。

### 官转一张图多少钱？为何扣费不同？

官转没有固定的单张价格，费用按实际 token 用量计算，单价见[官转计费](#官转计费)。

参数一样、扣费却不同，最常见的原因是 `quality` 没有传或传了 `auto`：这时由模型根据生成内容自行选档，同一个请求两次落在不同档位，输出 token 和费用就不同。

需要稳定预算时，显式传 `size` 和 `quality`，再用几次代表性请求的 `usage` 估算单张成本。实际扣费以[调用日志](https://api.laozhang.ai/log)为准。

### 请求失败或超时会扣费吗？

返回错误、没有生成图片的请求一般不扣费，例如参数错误、内容审核拦截、鉴权失败和限流。请求进入生成并返回图片后，官转按实际 token 扣费，`-vip` 与网页版按次扣费。

客户端超时或主动断开并不会取消服务端的生成，生成完成后照常扣费。高分辨率和高质量档位耗时更长，客户端超时要留足；超时后先在[调用日志](https://api.laozhang.ai/log)确认上一次请求的状态，再决定是否重试，避免重复生成和重复扣费。实际扣费以调用日志为准。

### response\_format 为何报错？

官转按 OpenAI 的规则返回 Base64 图片，不支持 DALL·E 时代的 `response_format` 参数，传了可能直接返回参数错误，删掉即可。需要图片链接时，把 `b64_json` 解码后上传到自己的对象存储。

按次模型也不要靠 `response_format` 指定返回形式。本页的 `save_images.py` 同时处理 `b64_json` 和 `url`，按响应中实际出现的字段保存即可，见[保存图片与查看结果](#保存图片与查看结果)。

### 编辑能传多张参考图或用 mask 吗？

官转可以，规则与 OpenAI 相同：

* 一次最多 16 张参考图，multipart 请求中重复传 `image[]` 字段；参考图按图片输入 tokens 计费，张数越多，输入费用越高。
* `mask` 只作用于第一张图，需要与这张图格式、尺寸相同，带 alpha 通道；mask 用 PNG，小于 4MB，原图小于 50MB。
* mask 只是引导，模型不一定严格沿着 mask 的边缘修改，上线前先用少量请求确认效果。

两款 `-vip` 模型不支持 `mask`。只想去掉背景时，用[透明背景 PNG](#透明背景-png) 中的参数和提示词。

## 相关文档

* [GPT Image 2：已有集成](/api-capabilities/gpt-image-2)
* [Images API 参考](/api-reference/images)
* [图像生成 API 选型与价格](/api-capabilities/image-generation-guide)
* [调用日志](/faq/call-logs)
* [模型与价格总表](/models)

## 参考资料

* [OpenAI Image generation](https://developers.openai.com/api/docs/guides/image-generation)
* [OpenAI Images API 参考](https://developers.openai.com/api/reference/resources/images)
* [OpenAI GPT Image 2.5 Flare](https://developers.openai.com/api/docs/models/gpt-image-2.5-flare)
* [OpenAI GPT Image 2.5 Sunburst](https://developers.openai.com/api/docs/models/gpt-image-2.5-sunburst)
* [老张API当前模型与价格](https://api.laozhang.ai/account/pricing)
* [GPT Image 2.5 上线公告](/announcements/gpt-image-2-5-2026-09)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.