> ## 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 图像编辑

> gpt-image-2 的单图文件上传、JSON Data URL 和已测编辑参数。

使用 `POST https://code.heihuzi.ai/v1/images/edits`，并显式指定 `model: "gpt-image-2"`。请使用具有图片权限的 API Key。

本页依据 **2026-09-13** 的该模型实际请求与图片结果整理，已验证单图 JSON Data URL 和 multipart 文件上传。GPT Image 2.5 Flare / Sunburst 请查看 [2.5 图像编辑](/cn/api-reference/images/gpt-image-2.5/edits)。

## 文件上传示例

下载[参考图 reference.png](/images/reference.png)，设置 `HEIHUZI_API_KEY` 后运行。字段与历史单文件实测一致，将蓝色杯子改为红色，响应保存到 `edits-multipart.json`。

<RequestExample>
  ```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' \
    --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
  ```
</RequestExample>

## JSON Data URL 请求体

请求头使用 `Content-Type: application/json` 和 Bearer 认证。将参考图编码为 base64 并填入完整 Data URL；下面的省略号必须替换为实际图片数据。

```json theme={null}
{
  "model": "gpt-image-2",
  "prompt": "Change the blue cup to a bright red cup. Keep the cup shape and the white background.",
  "images": [{"image_url": "data:image/png;base64,..."}],
  "n": 1,
  "size": "1024x1024",
  "quality": "low",
  "output_format": "png"
}
```

## 请求参数

<ParamField body="model" type="string" required>
  填写 `gpt-image-2`。调用此模型时必须显式指定，省略模型会使用 GPT Image 2.5 Flare。
</ParamField>

<ParamField body="prompt" type="string" required>
  描述要生成的画面或对参考图的修改要求。
</ParamField>

<ParamField body="n" type="integer" default="1">
  本页已测单张输出 `1`；省略时也返回一张图片。
</ParamField>

<ParamField body="size" type="string">
  本页已测固定尺寸 `1024x1024`。省略尺寸的历史测试返回 1254×1254；需要固定尺寸时请显式填写。
</ParamField>

<ParamField body="quality" type="string">
  已分别验证 `low`、`medium`、`high`、`auto`，测试使用单张 1024×1024 PNG。
</ParamField>

<ParamField body="output_format" type="string">
  本页已测 `png`，响应图片经解码确认为 PNG。
</ParamField>

<ParamField body="image" type="file">
  multipart 请求上传单张参考图，与 JSON 的 `images` 二选一。本页素材为 1024×1024 PNG。
</ParamField>

<ParamField body="images" type="object[]">
  JSON 请求传入单张参考图：`[{"image_url": "data:image/png;base64,..."}]`。`image_url` 填写完整 Data URL。
</ParamField>

## 响应示例

以下为 2026-09-13 该模型的实际响应节选，仅省略图片 base64。`data[].b64_json` 解码后得到图片；客户端应检查 HTTP 状态、错误字段和实际返回图片。

<ResponseExample>
  ```json theme={null}
  {
    "created": 1789275715,
    "background": "opaque",
    "data": [
      {
        "b64_json": "<此处省略真实图片的 base64>",
        "generation_id": "5fa6c7fb-a3e2-4648-b954-b59ef64928ff"
      }
    ],
    "output_format": "png",
    "quality": "low",
    "size": "1024x1024",
    "usage": {
      "input_tokens": 1049,
      "input_tokens_details": {
        "image_tokens": 1024,
        "text_tokens": 25
      },
      "output_tokens": 196,
      "output_tokens_details": {
        "image_tokens": 196,
        "text_tokens": 0
      },
      "total_tokens": 1245
    }
  }
  ```
</ResponseExample>

质量档位的历史矩阵使用 JSON 单图输入；multipart 单文件示例使用 `low`。本页不将 2.5 的远程 URL、多图、遮罩、透明输出和流式结果作为 GPT Image 2 的验证证据。