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

# GPT-Image-2.5 VIP 图像生成与编辑

> gpt-image-2.5-flare-vip 和 gpt-image-2.5-sunburst-vip 同步图片接口, 支持五档质量, 像素尺寸和按实际 token 后付费

VIP 版使用同步图片接口. 生成完成后, 同一次 HTTP 响应直接返回 Base64 图片和 `usage`, 无需查询任务状态.

| 模型           | 请求中的 model                   |
| ------------ | ---------------------------- |
| Flare VIP    | `gpt-image-2.5-flare-vip`    |
| Sunburst VIP | `gpt-image-2.5-sunburst-vip` |

`gpt-image-2.5-vip` 是文档中的系列名称. 调用时请使用表中的完整模型名.

<Note>
  普通版采用异步任务和按分辨率计价, 请查看独立的 [GPT-Image-2.5 文档](../gpt-image-2.5/generation). 两版的 size 格式和返回结构不同.
</Note>

中国大陆用户可将示例中的 `https://api.toapis.com` 替换为 `https://api.toapis.cn`. 使用 [ToAPIs 控制台](https://toapis.com/dashboard) 创建的 API Key.

## 快速开始

将自己的 API Key 设置为环境变量 `TOAPIS_API_KEY`. 下例将完整响应保存在 `response.json`, 便于同时读取图片和 usage:

```bash theme={null}
curl --fail-with-body --max-time 300 \
  --request POST \
  --url https://api.toapis.com/v1/images/generations \
  --header "Authorization: Bearer $TOAPIS_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-image-2.5-flare-vip",
    "prompt": "儿童绘本风格, 一位兽医用听诊器给小水獭检查心跳",
    "quality": "low",
    "size": "1024x1024",
    "n": 1
  }' \
  --output response.json
```

确认 curl 成功后, 使用 Python 3 解码为图片. 该方式兼容 macOS 和 Linux:

```bash theme={null}
python3 - <<'PY'
import base64
import json
from pathlib import Path

response = json.loads(Path("response.json").read_text())
if "error" in response:
    raise SystemExit(response["error"])
Path("otter.png").write_bytes(base64.b64decode(response["data"][0]["b64_json"]))
print(response.get("usage"))
PY
```

五档质量均可使用同一个接口. 高质量请求可能超过 120 秒, 请为同步生成预留足够的客户端超时. 上例的 300 秒是客户端设置, 不代表完成时限承诺. 网络超时后先查看平台使用日志, 确认原请求是否成功, 再决定是否重新提交.

## 生成请求参数

<ParamField header="Authorization" type="string" required>
  使用 `Bearer YOUR_TOAPIS_API_KEY` 认证.
</ParamField>

<ParamField body="model" type="string" required>
  `gpt-image-2.5-flare-vip` 或 `gpt-image-2.5-sunburst-vip`.
</ParamField>

<ParamField body="prompt" type="string" required>
  图片描述. 编辑时描述需要保留和修改的内容.
</ParamField>

<ParamField body="quality" type="string" default="high">
  支持 `low`, `medium`, `high`, `xhigh`, `max` 五档, 默认 `high`. 使用小写值.

  quality 影响生成质量和实际输出 token. 相同 quality 的图片也可能因尺寸和内容不同而产生不同费用.
</ParamField>

<ParamField body="size" type="string" default="1024x1024">
  输出像素尺寸, 使用 `宽x高` 格式. 例如 `1024x1024`, `1536x1024`, `1024x1536`, `1280x1024`.

  支持上游允许的自定义像素尺寸, 不限于上述示例. 合法尺寸范围以接口校验为准. VIP 示例不使用 `1:1` 这样的比例值, 也不需要额外传入 resolution.
</ParamField>

<ParamField body="n" type="integer" default={1}>
  每次请求使用 `1`, 生成一张图片.
</ParamField>

## 参考图编辑

编辑使用 `POST /v1/images/edits`, 请求为 `multipart/form-data`. 将本地图片放在 `image` 文件字段中, 同时传入 `model`, `prompt`, `quality`, `size` 和 `n`.

下例使用 Sunburst VIP, 给 `otter.png` 中的小水獭增加黄色围巾:

```bash theme={null}
curl --fail-with-body --max-time 300 \
  --request POST \
  --url https://api.toapis.com/v1/images/edits \
  --header "Authorization: Bearer $TOAPIS_API_KEY" \
  --form 'model=gpt-image-2.5-sunburst-vip' \
  --form 'prompt=保留原图中的小水獭和兽医, 给小水獭增加一条黄色围巾' \
  --form 'image=@otter.png;type=image/png' \
  --form 'quality=low' \
  --form 'size=1024x1024' \
  --form 'n=1' \
  --output edited-response.json
```

让 curl 自动设置 multipart 的 Content-Type 和 boundary. 将前文解码脚本中的 `response.json` 改为 `edited-response.json`, 输出文件改为 `edited-otter.png`, 即可保存编辑结果.

Flare VIP 也支持同样的编辑方式, 将 model 改为 `gpt-image-2.5-flare-vip` 即可. 参考图输入会产生图片输入 token 费用.

## 响应和 usage

生成和编辑均返回同步图片响应. 以下 usage 来自一次 `low` 质量的 1024x1024 文生图, 图片数据已省略:

```json theme={null}
{
  "created": 1788951900,
  "data": [
    {"b64_json": "BASE64_IMAGE_DATA"}
  ],
  "usage": {
    "input_tokens": 27,
    "input_tokens_details": {
      "text_tokens": 27,
      "image_tokens": 0
    },
    "output_tokens": 196,
    "output_tokens_details": {
      "image_tokens": 196,
      "text_tokens": 0
    },
    "total_tokens": 223
  }
}
```

| 字段                                        | 含义                      |
| ----------------------------------------- | ----------------------- |
| `data[0].b64_json`                        | 图片 Base64 内容            |
| `usage.input_tokens`                      | 输入 token 总数, 已包含文本和图片输入 |
| `usage.input_tokens_details.text_tokens`  | 文本输入 token              |
| `usage.input_tokens_details.image_tokens` | 图片输入 token, 文生图通常为 0    |
| `usage.output_tokens`                     | 图片输出 token              |
| `usage.total_tokens`                      | 输入和输出 token 之和          |

输入明细是 `input_tokens` 的拆分, 计算费用时不要把总数和明细重复相加. 上游报告缓存命中时, 缓存 token 属于对应的文本或图片输入子集. 缓存字段可能省略, 不能假定每次请求都命中缓存.

## token 价格

以下为 2026-09-09 核对的标准价格, 两个 VIP 模型相同, 按官方 token 单价的 8 折计费:

| 类型     | USD/百万 token |
| ------ | -----------: |
| 文本输入   |         4.00 |
| 缓存文本输入 |         1.00 |
| 图片输入   |         6.40 |
| 缓存图片输入 |         1.60 |
| 图片输出   |        24.00 |

五档 quality 共用上述 token 单价. VIP 没有按 quality 固定的每张价格, 请求完成后按实际 usage 结算. 按实际 token 后付费是指完成后结算实际费用, 调用前仍需有足够的账户余额和 API Key 额度.

费用公式, 单位为 USD:

```text theme={null}
费用 = (
  未缓存文本输入 token * 4
  + 缓存文本输入 token * 1
  + 未缓存图片输入 token * 6.4
  + 缓存图片输入 token * 1.6
  + 图片输出 token * 24
) / 1,000,000
```

例如, 上述文生图的 27 个文本输入 token 和 196 个图片输出 token, 费用为:

```text theme={null}
(27 * 4 + 196 * 24) / 1,000,000 = $0.004812
```

一次参考图编辑实测包含 21 个文本输入 token, 1024 个图片输入 token 和 196 个图片输出 token. 公式金额为 $0.0113416, 按平台额度最小单位舍入后实扣 $0.011342. 这些是具体请求的示例, 不代表同一质量下每张图的固定费用.

账户专属定价或折扣可能不同, 最新价格以 [模型定价页](https://toapis.com/pricing) 和账户实际配置为准. 最终扣费可在使用日志中核对.

## 从普通版切换

1. 将完整模型名改为对应的 `-vip` 模型名.
2. 将 size 从比例改为像素尺寸, 并省略 resolution.
3. 文生图直接读取同步响应中的 `data[0].b64_json` 和 `usage`.
4. 参考图编辑改用 `/v1/images/edits` 上传图片文件.
5. 按实际 token 预估费用, 同时为同步请求设置足够的超时.

普通版的异步提交和任务查询示例见 [GPT-Image-2.5 文档](../gpt-image-2.5/generation).