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

# GPT-Image-2.5 · 图生图

> GPT-Image-2.5 Flare / Sunburst · POST /v1/images/edits

## 简介

GPT-Image-2.5 的 **Flare** 和 **Sunburst** 均支持基于参考图片和文字指令进行编辑。本页介绍 `POST /v1/images/edits`，适用于替换背景、修改颜色、风格迁移、局部重绘和多图参考等任务。

请在 `prompt` 中明确需要修改和保留的内容，并通过 JSON 图片引用或 multipart 上传参考图。局部区域可使用 mask 蒙版或 markup 透明圈注层，二者不能同时提供。Flare 适合快速迭代，Sunburst 适合更看重细节和编辑精度的场景。

### 模型选择

| 模型 ID | 适用场景 |
| - | - |
| `gpt-image-2.5-flare` | 快速迭代、交互式生成 |
| `gpt-image-2.5-sunburst` | 复杂布局、细节表现与精确编辑 |

两个模型共用本页的端点、参数和响应结构。示例默认使用 Flare；切换为 Sunburst 时只需替换请求中的 `model`，其他字段按实际需求设置。

## 认证

**Authorization** `string` *required*

Bearer \$GRAVITEX\_API\_KEY

**Content-Type** `string` *required*

application/json / multipart/form-data

## 请求参数

| 参数 | 类型 | 说明 |
| - | - | - |
| `model` | string | 必填，gpt-image-2.5-flare 或 gpt-image-2.5-sunburst |
| `prompt` | string | 必填，描述图片修改要求，最长 32,000 字符 |
| `quality` | string | auto / low / medium / high / xhigh / max；默认 auto |
| `size` | string | auto 或 WxH，宽高为 16 的倍数；受模型尺寸和总像素预算约束 |
| `n` | integer | 1–10；默认 1 |
| `background` | string | auto / opaque / transparent；透明栅格输出使用 png 或 webp |
| `output_format` | string | png / jpeg / webp；默认 png |
| `output_compression` | integer | 0–100，默认 100，仅用于 JPEG / WebP |
| `moderation` | string | auto / low；默认 auto |
| `safety_identifier` | string | 稳定的终端用户标识，建议哈希化，最长 128 字符；替代 user |
| `stream` | boolean | 默认 false；开启后返回 SSE 事件，不能按普通 JSON 响应解析 |
| `partial_images` | integer | 仅栅格流式输出，0–3，默认 0；表示期望的中间预览数，实际可能更少 |
| `images` / `image[]` | array / file | JSON 必填，至少一张参考图；使用 `images: [{"image_url": "HTTPS URL 或 base64 data URI"}]`。multipart 改用 image\[] 文件字段 |
| `markup` | object / file | 可选透明 PNG 圈注层，叠加在第一张参考图上；与 mask 互斥 |
| `mask` | object / file | 可选 PNG 蒙版，尺寸须与第一张参考图一致并包含 alpha 通道；完全透明区域表示需要编辑的位置。多图输入仅作用于第一张图；与 markup 互斥 |

### images / markup / mask

JSON 使用 `images: [{"image_url": "https://..."}]`；也可传 base64 data URI。multipart 使用 `image[]` 上传文件。平台会将 JSON 编辑转为 multipart；不支持 OpenAI `file_id` 引用。此转换行为来自平台接入说明。

`markup` 是叠加在第一张参考图上的透明 PNG 圈注层，须含透明像素，尺寸匹配第一张图旋正后的尺寸。JSON 用 `markup: {"image_url": "https://..."}`，multipart 上传 markup 文件。与 mask 互斥。

`mask` 可用于标识编辑区域，与 markup 二选一；JSON 使用 image\_url，multipart 上传文件。

## 请求示例

示例从环境变量 `GRAVITEX_API_KEY` 读取平台令牌，请先在当前终端设置该变量。文件上传使用 curl 的 `-F` 自动生成 Content-Type 和 boundary，不要手动把 Content-Type 固定成 multipart/form-data。

> [!NOTE]
>
> 图片引用请使用可访问的 HTTPS URL 或 base64 data URI。multipart 示例先下载官方图片再上传。平台接入说明不支持 OpenAI file\_id 引用；2.6 的历史测试状态码不作为 2.5 的行为保证。

### JSON

```bash theme={null}
curl https://api.gravitex.ai/v1/images/edits \
  -H "Authorization: Bearer $GRAVITEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-image-2.5-flare",
  "prompt": "Change the vase to blue. Keep everything else unchanged.",
  "quality": "medium",
  "size": "1024x1024",
  "images": [
    {
      "image_url": "https://developers.openai.com/images/platform/guides/image-prompting/kitchen.webp"
    }
  ]
}'
```

### multipart/form-data

```bash theme={null}
curl --fail --location "https://developers.openai.com/images/platform/guides/image-prompting/kitchen.webp" -o kitchen.webp

curl https://api.gravitex.ai/v1/images/edits \
  -H "Authorization: Bearer $GRAVITEX_API_KEY" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=Change the vase to blue. Keep everything else unchanged." \
  -F "image[]=@kitchen.webp"
```

### 圈注编辑

```bash theme={null}
curl https://api.gravitex.ai/v1/images/edits \
  -H "Authorization: Bearer $GRAVITEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-image-2.5-flare",
  "prompt": "Change the vase to blue. Keep everything else unchanged.",
  "quality": "medium",
  "size": "1024x1024",
  "images": [
    {
      "image_url": "https://developers.openai.com/images/platform/guides/image-prompting/kitchen.webp"
    }
  ],
  "markup": {
    "image_url": "https://developers.openai.com/images/platform/guides/image-prompting/markup-vase-overlay-gpt-image-2-6.png"
  }
}'
```

`user` 为兼容旧请求保留，已废弃；新请求使用 safety\_identifier。非空 safety\_identifier 优先，未提供、null 或空字符串时才回退 user。

### 蒙版局部重绘

```bash theme={null}
curl https://api.gravitex.ai/v1/images/edits \
  -H "Authorization: Bearer $GRAVITEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-image-2.5-flare",
  "prompt": "Add a pink flamingo float in the masked pool area. Keep the rest of the room unchanged.",
  "images": [
    {
      "image_url": "https://cdn.openai.com/API/docs/images/sunlit_lounge.png"
    }
  ],
  "mask": {
    "image_url": "https://cdn.openai.com/API/docs/images/mask.png"
  },
  "quality": "medium"
}'
```

### 流式输出

```bash theme={null}
curl --no-buffer https://api.gravitex.ai/v1/images/edits \
  -H "Authorization: Bearer $GRAVITEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-image-2.5-flare",
  "prompt": "Change the vase to blue. Keep everything else unchanged.",
  "quality": "medium",
  "size": "1024x1024",
  "stream": true,
  "partial_images": 1,
  "images": [
    {
      "image_url": "https://developers.openai.com/images/platform/guides/image-prompting/kitchen.webp"
    }
  ]
}'
```

## 限制与注意事项

auto 为默认值。显式尺寸使用 WxH，宽高均为 16 的倍数，宽高比在 1:3–3:1 之间。image-2 官方指南规定最长边不超过 3840px、总像素为 655,360–8,294,400；2.5 的 API 参考也要求尺寸符合模型的边长和像素预算。2.6（尤其 GIF）的预算请按模型和项目实际支持确认，不直接套用旧模型上限。

官方 Images API 的 JSON 编辑支持 **1–16 张**输入图片，PNG / JPEG / WebP，每张小于 **50MB**。mask 为带 alpha 通道的 PNG，须与第一张参考图尺寸一致；透明区域指定编辑位置，蒙版用于引导生成，不保证像素级硬裁剪。请勿把平台未主动校验理解为上游无限制。

本页仅列出官方明确说明的 GPT-Image-2.5 用法，不将 2.6 的 complexity、GIF、SVG 专属说明直接套用到 2.5。通用 API schema 出现某字段，不代表所有模型和渠道都支持。

## 响应示例

下面是非流式响应的结构示意，图片数据和 token 数仅为示例，并非实际生成结果。将 b64\_json 解码为对应格式的文件；不要将 Base64 字符串直接保存为图片。

```json theme={null}
{
  "created": 1794268800,
  "data": [
    {
      "b64_json": "<BASE64_IMAGE_DATA>"
    }
  ],
  "usage": {
    "input_tokens": 100,
    "output_tokens": 824,
    "total_tokens": 924
  }
}
```

若设置 `stream: true`，响应为 SSE 事件流；按事件读取中间预览和最终图片，不能对整个响应直接调用 JSON 解析。

## 响应与计费

本页示例为非流式调用时，图片通过 b64\_json 返回；不要传 response\_format=url 期待图片链接。输入图片和输出图片均有 token 用量；相同 token 单价不代表相同单张费用，需结合实际 usage。

返回 `data[].b64_json` 和 `usage`。图片数据须先 Base64 解码再保存。以下为 OpenAI 官方标准价，不是 GravitexAI 报价。

缓存价格是官方参考费率。官方指南说明，GPT Image 2 / 2.5 的缓存输入优惠仅适用于 Responses API 图像工具，不适用于直接调用本页 Images API（含 edits）；平台实际结算以控制台为准。

| 类型 | 美元 / 1M tokens |
| - | - |
| 文本输入 | \$5.00 |
| 缓存文本输入 | \$1.25 |
| 图片输入 | \$8.00 |
| 缓存图片输入 | \$2.00 |
| 图片输出 | \$30.00 |

## 官方参考

* [Image generation guide](https://developers.openai.com/api/docs/guides/image-generation)
* [API Reference](https://developers.openai.com/api/reference/resources/images/methods/edit)
* [Flare](https://developers.openai.com/api/docs/models/gpt-image-2.5-flare)
* [Sunburst](https://developers.openai.com/api/docs/models/gpt-image-2.5-sunburst)
* [Pricing](https://developers.openai.com/api/docs/pricing)


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