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

# GPT-Image-2.5 图像生成

>  - 提供 gpt-image-2.5-flare 与 gpt-image-2.5-sunburst 两种模型
- 异步处理模式，返回 task_id 用于后续查询
- 支持文生图与最多 16 张参考图的图像编辑
- 支持使用透明 PNG 蒙版进行局部重绘
- 支持 15 种比例、精确像素尺寸以及 1K / 2K / 4K 分辨率
- 支持 low / medium / high / xhigh / max 五档质量 

> [!NOTE]
>
> **如何选择模型：** `gpt-image-2.5-flare` 速度更快，适合日常高质量出图、批量生成和快速原型；`gpt-image-2.5-sunburst` 更强调编辑精度，适合成品级商品图、投放创意和多轮精细编辑。两者计费标准相同。

```bash cURL theme={null}
curl --request POST \
  --url https://gccai.heqingsong.uk/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-image-2.5-flare",
    "prompt": "雨天窗边温暖舒适的阅读角，暖色台灯，电影感光影",
    "size": "1:1",
    "resolution": "1k",
    "quality": "medium",
    "n": 1
  }'
```

```python Python theme={null}
import requests

response = requests.post(
    "https://gccai.heqingsong.uk/v1/images/generations",
    headers={
        "Authorization": "Bearer <token>",
        "Content-Type": "application/json",
    },
    json={
        "model": "gpt-image-2.5-flare",
        "prompt": "雨天窗边温暖舒适的阅读角，暖色台灯，电影感光影",
        "size": "1:1",
        "resolution": "1k",
        "quality": "medium",
        "n": 1,
    },
)

print(response.json())
```

```javascript JavaScript theme={null}
const response = await fetch(
  "https://gccai.heqingsong.uk/v1/images/generations",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer <token>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "gpt-image-2.5-flare",
      prompt: "雨天窗边温暖舒适的阅读角，暖色台灯，电影感光影",
      size: "1:1",
      resolution: "1k",
      quality: "medium",
      n: 1,
    }),
  },
);

console.log(await response.json());
```

```json 200 theme={null}
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01KXXXXXXXXXXXXXXX"
    }
  ]
}
```

```json 400 theme={null}
{
  "error": {
    "code": 400,
    "message": "请求参数无效",
    "type": "invalid_request_error"
  }
}
```

```json 401 theme={null}
{
  "error": {
    "code": 401,
    "message": "身份验证失败，请检查您的 API 密钥",
    "type": "authentication_error"
  }
}
```

```json 402 theme={null}
{
  "error": {
    "code": 402,
    "message": "账户余额不足，请充值后再试",
    "type": "payment_required"
  }
}
```

```json 429 theme={null}
{
  "error": {
    "code": 429,
    "message": "请求过于频繁，请稍后再试",
    "type": "rate_limit_error"
  }
}
```

```json 500 theme={null}
{
  "error": {
    "code": 500,
    "message": "服务器内部错误，请稍后重试",
    "type": "server_error"
  }
}
```

## 认证

**Authorization** `string` *required*

所有接口均使用 Bearer Token 认证。访问 [API Key 管理页面](https://gccai.heqingsong.uk/keys) 获取密钥。

```
Authorization: Bearer YOUR_API_KEY
```

## 模型选择

| 模型 | 特点 | 适用场景 |
| - | - | - |
| `gpt-image-2.5-flare` | 默认款，生成速度快 | 社媒内容、商品图、视觉搜索、快速原型、大批量生成 |
| `gpt-image-2.5-sunburst` | 编辑精度优先 | 投放级创意、成品级商品图、多轮精细编辑 |

两个模型的单价和相同参数下的 token 消耗一致，选择时只需考虑速度与质量取舍。

与 `gpt-image-2` 相比，GPT-Image-2.5 新增 `xhigh` 和 `max` 两个质量档位；`medium` 与 `high` 的输出 token 消耗约为上一代同名档位的四分之一。

## 请求参数

**model** `string` *required*

图像生成模型名称。可选值：

* `gpt-image-2.5-flare`
* `gpt-image-2.5-sunburst`

**prompt** `string` *required*

图像生成或编辑的文本描述。

支持中英文。建议说明主体、场景、构图、风格、光线以及需要保留或修改的内容。

**size** `string` (default: auto)

输出图像的比例或精确像素尺寸。

支持：

* `auto`：由模型根据提示词或参考图决定
* 比例名：`1:1`、`3:2`、`2:3`、`4:3`、`3:4`、`5:4`、`4:5`、`16:9`、`9:16`、`2:1`、`1:2`、`21:9`、`9:21`、`3:1`、`1:3`
* 精确像素：例如 `1600x1200`

> [!TIP]
>
> 图生图时建议不传 `size`，系统会根据输入图比例和 `resolution` 自动计算输出尺寸。

**resolution** `string` (default: 1k)

分辨率档位，与比例形式的 `size` 配合决定实际输出像素。

* `1k`（默认）
* `2k`
* `4k`

当 `size` 使用精确像素格式时，此字段会被忽略。

**quality** `string` (default: auto)

图片质量档位。

* `low`
* `medium`
* `high`
* `xhigh`
* `max`
* `auto`（默认，由模型运行时决定）

> [!WARNING]
>
> `xhigh` 和 `max` 仅 GPT-Image-2.5 支持。将其传给 `gpt-image-2` 会同步返回 400，不会自动降级。

**n** `integer` (default: 1)

生成图片数量，取值范围为 `1` \~ `4`。

必须传入数字，不要使用字符串。

**output\_format** `string` (default: png)

输出文件格式。

* `png`（默认，支持透明背景）
* `jpeg`
* `webp`（支持透明背景）

**output\_compression** `integer`

输出压缩强度，范围为 `0` \~ `100`，仅对 `jpeg` 和 `webp` 生效。

**background** `string`

背景模式。可选值：`transparent`、`opaque`、`auto`。

> [!WARNING]
>
> `background: "transparent"` 只能与 `output_format: "png"` 或 `output_format: "webp"` 搭配。JPEG 不支持 Alpha 通道。

**moderation** `string` (default: low)

内容审核强度。可选值：`auto`、`low`。

未传时，GccAi 会显式使用 `low`；传入 `auto` 时则按 `auto` 执行。

**image\_urls** `string[]`

图生图或图像编辑使用的参考图 URL 数组，最多 `16` 张。传入后自动进入编辑模式。

仅接受公网可访问的 HTTP(S) URL。本地图片请先调用 `POST /v1/uploads/images` 上传，再使用返回的 `url`。

**mask\_url** `string`

局部重绘使用的蒙版图，仅在同时传入 `image_urls` 时生效。`gpt-image-2.5-flare` 和 `gpt-image-2.5-sunburst` 均支持此参数。

参数为单个字符串，支持以下格式：

* 可由服务器直接下载的 HTTP(S) 图片直链
* `data:image/png;base64,...` 格式的 PNG Data URL

蒙版要求：

* 使用带 Alpha 透明通道的 PNG，建议输入原图也使用 PNG
* 像素宽高必须与 `image_urls[0]` 完全一致；匹配的是第一张输入原图，不是输出 `size`
* Alpha 完全透明（`alpha=0`）的区域表示需要修改，其余区域用于保留
* 一次只能传入一张蒙版；使用多张参考图时，蒙版仅作用于第一张输入图
* 文件大小指南写的是小于 `50 MB`，而 `mask` 参数说明写的是小于 `4 MB`；未实测前建议按更严格的 `4 MB` 准备

> [!WARNING]
>
> 普通黑白图片如果没有 Alpha 透明通道，不能直接作为蒙版。GccAi 不会自动补充透明通道，当前也不会预先校验蒙版与原图尺寸是否一致，这两点需由调用方保证。

> [!NOTE]
>
> HTTP(S) URL 必须无需 Cookie 或额外鉴权头即可访问；签名链接的有效期应覆盖任务排队和执行时间。默认下载限制为 `20 MB`，超时时间为 `60` 秒，具体部署可能覆盖这两个默认值。
>
> 蒙版用于引导模型编辑，模型不保证蒙版边界外的像素完全不变。

## 尺寸规则

使用精确像素尺寸时，宽高必须同时满足以下条件：

* 宽和高均为 `16` 的倍数
* 任意单边不超过 `3840` 像素
* 长边与短边之比不超过 `3:1`
* 总像素在 `655,360` \~ `8,294,400` 之间

> [!WARNING]
>
> 高于 2560×1440 的分辨率属于实验性范围，稳定性可能低于常用分辨率。

### 比例与分辨率映射

| `size` | `1k` | `2k` | `4k` |
| - | - | - | - |
| `1:1` | 1024×1024 | 2048×2048 | 2880×2880 |
| `3:2` | 1536×1024 | 2048×1360 | 3520×2336 |
| `2:3` | 1024×1536 | 1360×2048 | 2336×3520 |
| `4:3` | 1024×768 | 2048×1536 | 3312×2480 |
| `3:4` | 768×1024 | 1536×2048 | 2480×3312 |
| `5:4` | 1280×1024 | 2560×2048 | 3216×2576 |
| `4:5` | 1024×1280 | 2048×2560 | 2576×3216 |
| `16:9` | 1536×864 | 2048×1152 | 3840×2160 |
| `9:16` | 864×1536 | 1152×2048 | 2160×3840 |
| `2:1` | 2048×1024 | 2688×1344 | 3840×1920 |
| `1:2` | 1024×2048 | 1344×2688 | 1920×3840 |
| `21:9` | 2016×864 | 2688×1152 | 3840×1648 |
| `9:21` | 864×2016 | 1152×2688 | 1648×3840 |
| `3:1` | 1536×512 | 3072×1024 | 3840×1280 |
| `1:3` | 512×1536 | 1024×3072 | 1280×3840 |

也可以直接传入满足尺寸规则的任意精确像素值，不限于上表中的组合。

## 使用示例

### 文生图

```json theme={null}
{
  "model": "gpt-image-2.5-flare",
  "prompt": "未来感城市中的空中花园，清晨薄雾，建筑摄影",
  "size": "16:9",
  "resolution": "2k",
  "quality": "high",
  "n": 1
}
```

### 使用 Sunburst 精细编辑

```json theme={null}
{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "保留商品主体和包装文字，将背景替换为柔和的米白色摄影棚，并增加自然投影",
  "image_urls": [
    "https://example.com/product.png"
  ],
  "resolution": "2k",
  "quality": "xhigh"
}
```

### 使用蒙版局部重绘

以下示例只修改蒙版中 Alpha 完全透明的区域。蒙版尺寸必须与 `product.png` 一致：

```json theme={null}
{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "仅将透明蒙版覆盖的区域替换为金色丝带，保留商品主体和其他背景",
  "image_urls": [
    "https://example.com/product.png"
  ],
  "mask_url": "https://example.com/product-mask.png",
  "quality": "xhigh"
}
```

### 多参考图编辑

```json theme={null}
{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "以第一张图的商品为主体，参考第二张图的布景和第三张图的光线，生成横版广告图",
  "image_urls": [
    "https://example.com/product.png",
    "https://example.com/set.jpg",
    "https://example.com/lighting.jpg"
  ],
  "size": "16:9",
  "resolution": "2k",
  "quality": "max"
}
```

### 透明背景

```json theme={null}
{
  "model": "gpt-image-2.5-flare",
  "prompt": "一双白色运动鞋的电商产品图，主体完整，透明背景",
  "size": "1:1",
  "resolution": "2k",
  "quality": "high",
  "background": "transparent",
  "output_format": "png"
}
```

### 精确像素尺寸

```json theme={null}
{
  "model": "gpt-image-2.5-flare",
  "prompt": "极简风格的产品发布会主视觉",
  "size": "1600x1200",
  "quality": "medium"
}
```

## 提交响应

提交成功后会立即返回异步任务 ID：

```json theme={null}
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01KXXXXXXXXXXXXXXX"
    }
  ]
}
```

> [!WARNING]
>
> `data` 是数组，请读取 `data[0].task_id`。

## 查询任务结果

使用提交响应中的 `task_id` 调用 [任务查询接口](https://gccai.heqingsong.uk/cn/api-reference/tasks/status.md)：

```bash theme={null}
curl --request GET \
  --url https://gccai.heqingsong.uk/v1/tasks/task_01KXXXXXXXXXXXXXXX \
  --header 'Authorization: Bearer <token>'
```

建议每 2 \~ 5 秒轮询一次，直到状态变为 `completed` 或 `failed`。

### 任务成功

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01KXXXXXXXXXXXXXXX",
    "status": "completed",
    "progress": 100,
    "cost": 0.01325,
    "credits_cost": 0.1325,
    "result": {
      "images": [
        {
          "url": [
            "https://upload.gccai.ai/f/image/example.png"
          ],
          "expires_at": 1789000000
        }
      ]
    },
    "usage": {
      "input_tokens": 16,
      "output_tokens": 439,
      "total_tokens": 455
    }
  }
}
```

图片地址位于 `data.result.images[].url[]`。请及时下载并转存，不要将临时 URL 用作长期存储。

批量查询多个任务时，可使用 `POST /v1/tasks/batch`。

| 状态 | 含义 |
| - | - |
| `submitted` | 任务已提交 |
| `processing` | 正在生成 |
| `completed` | 生成成功，可读取 `result.images` |
| `failed` | 生成失败，查看 `error.message`；预扣费用会自动退回 |

## 计费说明

GPT-Image-2.5 按实际 token 用量计费，Flare 与 Sunburst 单价相同。最终费用请以 [价格页面](https://gccai.heqingsong.uk/pricing) 或 `/api/pricing` 返回的实时值为准。

### 官方 token 单价

| 项目 | 每 100 万 token 单价 |
| - | - |
| 图片输出 | \$30.00 |
| 图片输入 | \$8.00 |
| 图片输入（缓存命中） | \$2.00 |
| 文本输入 | \$5.00 |
| 文本输入（缓存命中） | \$1.25 |

实际扣费还会受到账号分组倍率和折扣影响。

### 1024×1024 输出 token 参考

| `quality` | 输出 token | 官方输出成本 |
| - | - | - |
| `low` | 196 | \$0.00588 |
| `medium` | 439 | \$0.01317 |
| `high` | 1756 | \$0.05268 |
| `xhigh` | 3122 | \$0.09366 |
| `max` | 7024 | \$0.21072 |

> [!WARNING]
>
> `quality: "auto"` 的实际档位由模型运行时决定。提交时会按当前尺寸的最高档 `max` 预留额度，任务完成后再按真实 token 用量结算并退回差额。余额敏感时建议显式指定 `quality`。

当 `n > 1` 时，预扣额度会按图片数量线性增加，最终按实际生成张数结算。任务失败会自动退款。

## 输出 token 参考表

下表为各比例、分辨率和质量组合的单张图片输出 token 参考值。实际账单还会包含提示词及参考图的输入 token。

| 尺寸 | 实际像素 | low | medium | high | xhigh | max |
| - | - | - | - | - | - | - |
| `1:1` | 1024×1024 | 196 | 439 | 1756 | 3122 | 7024 |
| `3:2` | 1536×1024 | 158 | 343 | 1372 | 2459 | 5488 |
| `2:3` | 1024×1536 | 158 | 343 | 1372 | 2459 | 5488 |
| `4:3` | 1024×768 | 134 | 301 | 1204 | 2140 | 4815 |
| `3:4` | 768×1024 | 134 | 301 | 1204 | 2140 | 4815 |
| `5:4` | 1280×1024 | 173 | 378 | 1510 | 2702 | 6119 |
| `4:5` | 1024×1280 | 173 | 378 | 1510 | 2702 | 6119 |
| `16:9` | 1536×864 | 120 | 280 | 1078 | 1917 | 4312 |
| `9:16` | 864×1536 | 120 | 280 | 1078 | 1917 | 4312 |
| `2:1` | 2048×1024 | 132 | 295 | 1180 | 2098 | 4720 |
| `1:2` | 1024×2048 | 132 | 295 | 1180 | 2098 | 4720 |
| `21:9` | 2016×864 | 105 | 225 | 943 | 1617 | 3682 |
| `9:21` | 864×2016 | 105 | 225 | 943 | 1617 | 3682 |
| `3:1` | 1536×512 | 56 | 134 | 535 | 937 | 2140 |
| `1:3` | 512×1536 | 56 | 134 | 535 | 937 | 2140 |
| `1:1@2k` | 2048×2048 | 397 | 892 | 3568 | 6343 | 14272 |
| `3:2@2k` | 2048×1360 | 211 | 460 | 1838 | 3216 | 7351 |
| `2:3@2k` | 1360×2048 | 211 | 460 | 1838 | 3216 | 7351 |
| `4:3@2k` | 2048×1536 | 247 | 556 | 2223 | 3952 | 8892 |
| `3:4@2k` | 1536×2048 | 247 | 556 | 2223 | 3952 | 8892 |
| `5:4@2k` | 2560×2048 | 377 | 826 | 3303 | 5911 | 13385 |
| `4:5@2k` | 2048×2560 | 377 | 826 | 3303 | 5911 | 13385 |
| `16:9@2k` | 2048×1152 | 157 | 367 | 1413 | 2511 | 5650 |
| `9:16@2k` | 1152×2048 | 157 | 367 | 1413 | 2511 | 5650 |
| `2:1@2k` | 2688×1344 | 180 | 405 | 1617 | 2874 | 6466 |
| `1:2@2k` | 1344×2688 | 180 | 405 | 1617 | 2874 | 6466 |
| `21:9@2k` | 2688×1152 | 143 | 306 | 1285 | 2202 | 5016 |
| `9:21@2k` | 1152×2688 | 143 | 306 | 1285 | 2202 | 5016 |
| `3:1@2k` | 3072×1024 | 103 | 247 | 988 | 1729 | 3952 |
| `1:3@2k` | 1024×3072 | 103 | 247 | 988 | 1729 | 3952 |
| `1:1@4k` | 2880×2880 | 659 | 1483 | 5930 | 10542 | 23719 |
| `3:2@4k` | 3520×2336 | 450 | 982 | 3926 | 6870 | 15703 |
| `2:3@4k` | 2336×3520 | 450 | 982 | 3926 | 6870 | 15703 |
| `4:3@4k` | 3312×2480 | 491 | 1104 | 4413 | 7845 | 17650 |
| `3:4@4k` | 2480×3312 | 491 | 1104 | 4413 | 7845 | 17650 |
| `5:4@4k` | 3216×2576 | 535 | 1173 | 4690 | 8393 | 19006 |
| `4:5@4k` | 2576×3216 | 535 | 1173 | 4690 | 8393 | 19006 |
| `16:9@4k` | 3840×2160 | 371 | 865 | 3336 | 5930 | 13342 |
| `9:16@4k` | 2160×3840 | 371 | 865 | 3336 | 5930 | 13342 |
| `2:1@4k` | 3840×1920 | 300 | 675 | 2700 | 4799 | 10798 |
| `1:2@4k` | 1920×3840 | 300 | 675 | 2700 | 4799 | 10798 |
| `21:9@4k` | 3840×1648 | 234 | 500 | 2099 | 3598 | 8196 |
| `9:21@4k` | 1648×3840 | 234 | 500 | 2099 | 3598 | 8196 |
| `3:1@4k` | 3840×1280 | 139 | 332 | 1328 | 2324 | 5311 |
| `1:3@4k` | 1280×3840 | 139 | 332 | 1328 | 2324 | 5311 |

## 限制

| 项目 | 限制 |
| - | - |
| 单次生成数量 `n` | 1 \~ 4 |
| 参考图数量 | 最多 16 张 |
| 单边像素 | 不超过 3840，且为 16 的倍数 |
| 总像素 | 655,360 \~ 8,294,400 |
| 长短边比例 | 不超过 3:1 |
| 输出格式 | PNG / JPEG / WebP |
| 透明背景 | 仅 PNG / WebP |
| 流式部分图 | 暂不支持 |

## 常见错误

| 场景 | 原因与处理 |
| - | - |
| `quality` 不受支持 | `xhigh` / `max` 仅支持 GPT-Image-2.5；更换模型或调整档位 |
| 精确像素宽高不是 16 的倍数 | 调整到满足尺寸规则的像素值 |
| `background=transparent` 搭配 `jpeg` | 将 `output_format` 改为 `png` 或 `webp` |
| 参考图超过 16 张 | 减少 `image_urls` 中的图片数量 |
| 账户余额不足 | 充值后重试；使用 `auto` 时需注意最高档预留额度 |

## Response

**code** `integer`

响应状态码，提交成功时为 200。

**data** `array`

提交响应数据。

**数组元素**

**status** `string`

初始状态为 `submitted`。

**task\_id** `string`

任务唯一标识符，用于查询任务状态和生成结果。


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