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

# GPT Image 2.6 图像编辑

> 上传参考图生成新图片或 GIF 动图的完整实测示例。

本页适用于 GPT Image 2.6。使用 2.5 请查看 [GPT Image 2.5 API](https://docs.heihuzi.ai/cn/api-reference/images/gpt-image-2.5/edits.md)。

通过 `POST https://code.heihuzi.ai/v1/images/edits` 上传参考图并描述修改要求。验证日期：**2026-11-07**。请使用具有 GPT Image 2.6 权限的 API Key，并设置环境变量 `HEIHUZI_API_KEY`。

## 输入方式

| 输入方式 | 本次验证的字段 | 模型 |
| - | - | - |
| 文件上传 | multipart 文件字段 `image`；多张时重复上传 `image[]` | Flare、Sunburst |
| JSON Data URL | `images: [{"image_url": "data:image/png;base64,..."}]` | Flare、Sunburst |
| JSON 图片地址 | `images: [{"image_url": "https://..."}]` | Sunburst |

下载[参考图 reference.png](https://docs.heihuzi.ai/images/reference.png)到运行目录后，可以直接运行下面的示例。

```bash theme={null}
curl --fail-with-body --silent --show-error --max-time 600 \
  --request POST \
  --url https://code.heihuzi.ai/v1/images/edits \
  --header "Authorization: Bearer $HEIHUZI_API_KEY" \
  --form 'model=gpt-image-2.6-sunburst' \
  --form 'prompt=Change the blue cup to a bright red cup. Keep the cup shape and the white background.' \
  --form 'image=@reference.png' \
  --form 'n=1' \
  --form 'size=1024x1024' \
  --form 'quality=low' \
  --form 'output_format=png' \
  --output edits-multipart.json
```

响应保存为 `edits-multipart.json`，其中 `data[].b64_json` 是输出图片。

## 请求参数

参数名、取值和返回结构与 OpenAI 官方 `POST /v1/images/edits` 一致。下面只列编辑接口实际调用过的取值，具体组合见[已验证的参数组合](#已验证的参数组合)。

**model** `string` *required*

填写 `gpt-image-2.6-flare` 或 `gpt-image-2.6-sunburst`。省略时本站使用 `gpt-image-2.5-flare`，和官方默认的 `gpt-image-2.5-sunburst` 不同，要用 2.6 请明确填写。

**prompt** `string` *required*

描述要怎样修改参考图。

**images** `object[]`

JSON 参考图数组，已验证一张和两张参考图。multipart 改用 `image` 文件字段，多张时重复上传 `image[]`。

**JSON 参考图字段**

**image\_url** `string`

参考图的完整 Data URL 或公开的 `https` 图片地址，本次验证 PNG。

官方的 `images[].file_id` 本站不支持，实测返回 400，请改用 `image_url`。

**background** `string`

已验证 `transparent`：配 `png` 得到透明背景的 PNG。实际背景以响应里的 `background` 为准。

**complexity** `string`

出图前构思的程度，已验证 `low`、`medium`、`high`，输出用量不变。

**frame\_count** `integer`

GIF 的帧数，只用于 `output_format: "gif"`。已验证 `2`、`4`、`9`、`12`、`16`，不填时为 9 帧。

**frame\_duration\_ms** `integer`

GIF 每帧时长，单位毫秒。已验证 `20`、`100`、`200`、`500`、`2000`，不填时为 200。

**moderation** `string`

内容审核档位，已验证 `low`、`auto`。

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

返回图片张数，已验证 `1`、`2`、`10`。一次出多张时，参考图的输入用量按张数重复计算：一张 1024×1024 参考图出 10 张，计 10240 个图片输入用量。

**output\_compression** `integer`

已验证 `jpeg` 填 `50`。

**output\_format** `string`

已验证 `png`、`jpeg`、`webp`、`gif`。GIF 两款型号、multipart 和 JSON 两种写法都验证过，见下方[参考图生成 GIF](#参考图生成-gif)。

**partial\_images** `integer`

流式返回时的预览张数。已验证 `1`、`2`：填 `2` 收到 2 张预览，填 `1` 没有收到预览。请求 `webp` 时预览图仍是 PNG，完成图是 WebP。

**quality** `string`

已验证 `low`、`medium`、`high`、`xhigh`、`max`、`auto`。`auto` 本次实际落在 `medium`，以响应里的 `quality` 为准。

**safety\_identifier** `string`

用于标识你这边的终端用户，响应里会原样返回。同时填写已弃用的 `user` 时，响应以 `safety_identifier` 为准。

**size** `string`

已验证 `1024x1024`、`1536x1024`、`1024x1536`、`2048x2048`、`2880x2880`、`auto`（本次返回 `1374x1145`）。GIF 不填和填 `512x512` 都输出 512×512，填 `1024x1024` 返回 400。

**stream** `boolean` (default: false)

设置 `true` 后返回 SSE。Flare、Sunburst，multipart 和 JSON 请求都验证过。完成事件是 `image_edit.completed`；填了 `partial_images` 时，之前可能先收到 `image_edit.partial_image` 预览事件。请以完成事件作为成功依据。

## 已验证的参数组合

以下每行都在正式环境实际调用，返回 200 并核对了图片文件。

| 模型 | 写法 | 尺寸 | 质量 | 格式 | 其他 | 实际结果 |
| - | - | - | - | - | - | - |
| Sunburst | multipart `image` | `1024x1024` | `low` | `png` | | 1024×1024 PNG，杯子变红 |
| Flare | JSON Data URL | `1024x1024` | `low` | `png` | | 1024×1024 PNG，杯子变红 |
| Flare | multipart 两个 `image[]` | `1536x1024` | `medium` | `jpeg` | `n: 2`、`output_compression: 50` | 两张 1536×1024 JPEG，第一张图的杯形配第二张图的红色 |
| Sunburst | JSON `https` 图片地址 | `2048x2048` | `high` | `webp` | `stream: true`、`partial_images: 2` | 2 张 PNG 预览和 2048×2048 WebP 完成图 |
| Sunburst | multipart `image` | `2880x2880` | `low` | `png` | `stream: true` | 2880×2880 PNG 完成图 |
| Flare | multipart `image` | `1024x1024` | `low` | `png` | `stream: true`、`partial_images: 1` | 1024×1024 PNG 完成图，没有预览 |
| Flare | JSON Data URL | `auto` | `auto` | `png` | `background: "transparent"`、`moderation: "low"`、`safety_identifier`、`user` | 1374×1145 透明背景 PNG，质量 `medium` |
| Flare | JSON Data URL | `1024x1536` | `max` | `png` | | 1024×1536 PNG |
| Sunburst | JSON Data URL | `1024x1024` | `xhigh` | `png` | `complexity: "low"` | 1024×1024 PNG |
| Flare | JSON Data URL | `1024x1024` | `low` | `png` | `complexity` 分别为 `medium`、`high` | 均为 1024×1024 PNG |
| Flare | JSON Data URL | `1024x1024` | `low` | `png` | `n: 10` | 十张 1024×1024 PNG |
| Flare | JSON Data URL | 省略 | `low` | `gif` | `frame_count: 9`、`frame_duration_ms: 200` | 512×512 GIF，9 帧，每帧 200 毫秒 |
| Sunburst | multipart `image` | 省略 | `low` | `gif` | `frame_count: 4`、`frame_duration_ms: 100` | 512×512 GIF，4 帧，每帧 100 毫秒 |
| Flare | JSON Data URL | `512x512` | `low` | `gif` | `frame_count: 12`、`frame_duration_ms: 500`、`moderation: "auto"` | 512×512 GIF，12 帧，每帧 500 毫秒 |
| Sunburst | JSON Data URL | 省略 | `low` | `gif` | `frame_count: 16`、`frame_duration_ms: 2000` | 512×512 GIF，16 帧，每帧 2000 毫秒 |
| Flare | JSON Data URL | 省略 | `low` | `gif` | `frame_count: 2`、`frame_duration_ms: 20` | 512×512 GIF，2 帧，每帧 20 毫秒 |
| Flare | multipart `image` | 省略 | `low` | `gif` | 不填帧数和帧时长 | 512×512 GIF，9 帧，每帧 200 毫秒 |

跨行叠加参数会形成新的组合，请先在自己的业务里验证再使用。参数不合法时返回的 400 结构见[图像生成的错误返回](https://docs.heihuzi.ai/cn/api-reference/images/gpt-image-2.6/generation.md#错误返回)。

## JSON 编辑并保存图片

这段完整代码已真实执行，把蓝色杯子改成红色并保存为 `edited-1.png`。

```python theme={null}
import base64
import os
from pathlib import Path
import requests

encoded = base64.b64encode(Path("reference.png").read_bytes()).decode("ascii")
response = requests.post(
    "https://code.heihuzi.ai/v1/images/edits",
    headers={"Authorization": f"Bearer {os.environ['HEIHUZI_API_KEY']}"},
    json={
        "model": "gpt-image-2.6-flare",
        "prompt": "Change the blue cup to a bright red cup. Keep the cup shape and the white background.",
        "images": [{"image_url": f"data:image/png;base64,{encoded}"}],
        "n": 1,
        "size": "1024x1024",
        "quality": "low",
        "output_format": "png",
    },
    timeout=600,
)
response.raise_for_status()
data = response.json()["data"]
for index, item in enumerate(data, 1):
    Path(f"edited-{index}.png").write_bytes(base64.b64decode(item["b64_json"]))
print("Saved", len(data), "image(s)")
```

## 参考图生成 GIF

这段完整代码已真实执行，让参考图里的杯子上下跳动，保存为 512×512、9 帧的 `cup-bounce.gif`。

```python theme={null}
import base64
import os
from pathlib import Path
import requests

encoded = base64.b64encode(Path("reference.png").read_bytes()).decode("ascii")
response = requests.post(
    "https://code.heihuzi.ai/v1/images/edits",
    headers={"Authorization": f"Bearer {os.environ['HEIHUZI_API_KEY']}"},
    json={
        "model": "gpt-image-2.6-flare",
        "prompt": "Make the blue cup gently bounce up and down.",
        "images": [{"image_url": f"data:image/png;base64,{encoded}"}],
        "quality": "low",
        "output_format": "gif",
        "frame_count": 9,
        "frame_duration_ms": 200,
    },
    timeout=600,
)
response.raise_for_status()
item = response.json()["data"][0]
Path("cup-bounce.gif").write_bytes(base64.b64decode(item["b64_json"]))
print("Saved cup-bounce.gif")
```

## 真实响应节选

下面是页首示例的一次真实响应，图片 base64 已省略。

```json theme={null}
{
  "created": 1794058909,
  "background": "opaque",
  "data": [
    {
      "b64_json": "<此处省略真实图片的 base64>",
      "generation_id": "e8ea7f47-4b57-4655-a6fe-c5e374a2bae5"
    }
  ],
  "output_format": "png",
  "quality": "low",
  "safety_identifier": null,
  "size": "1024x1024",
  "usage": {
    "input_tokens": 1059,
    "input_tokens_details": {
      "image_tokens": 1024,
      "text_tokens": 35
    },
    "output_tokens": 824,
    "output_tokens_details": {
      "image_tokens": 824,
      "text_tokens": 0
    },
    "total_tokens": 1883
  }
}
```

参考图会计入输入用量：这张 1024×1024 参考图计 1024 个图片输入用量。


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