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

# GPT-Image-2 图像编辑 API | 多参考图融合与 Mask Inpainting 局部重绘

> 使用 GPT-Image-2 编辑模式：在请求中加入 image_urls（最多 4 张）即自动切换为图像编辑，支持多参考图融合与 mask_url 遮罩局部重绘（inpainting）。quality 可选 low/medium/high，output_format 支持 png/jpeg，异步任务返回。

## 接口说明

**端点：** `POST https://geekapis.com/v1/images/generations`

图像编辑模式与文生图使用**相同端点**——只需在请求中加入 `image_urls` 字段，系统即自动切换为编辑模式。支持以下三种典型用法：

* **图生图（多参考图融合）**：提供 1–4 张参考图 + `prompt`，生成融合多图风格或内容的新图
* **局部重绘（inpainting）**：额外提供 `mask_url`，精确控制图像中需重新绘制的区域
* **风格迁移**：以参考图为样本，配合详细 `prompt` 生成指定风格的高清图像

接口采用**同步任务**模式

<Note>
  编辑模式与生成模式完全兼容，无需切换端点。在标准生成请求基础上加入 `image_urls`（以及可选的 `mask_url`）即可启用编辑模式。
</Note>

***

## 请求参数

### 认证

所有请求须在 Header 中携带 Bearer Token：

```text theme={null}
Authorization: Bearer YOUR_API_KEY
```

前往 [API Key 管理页面](https://geekapis.com/keys) 获取您的密钥。

### Body 参数

<ParamField body="model" type="string" required>
  图像生成模型名称。固定填写 `gpt-image-2`。
</ParamField>

<ParamField body="prompt" type="string" required>
  描述期望的编辑效果。

  示例：`"把背景换成星空，保持主体人物不变"` 或 `"将两张参考图融合成赛博朋克风格插画海报"`
</ParamField>

<ParamField body="image_urls" type="string[]" required>
  参考图 URL 数组（**触发编辑模式的关键字段**）。

  * 最多 **4 张**
  * 支持 PNG / JPG 格式，单张 ≤ 2MB
</ParamField>

<ParamField body="mask_url" type="string">
  遮罩图 URL，用于局部重绘（inpainting）。

  * 须为 **PNG 格式**，且包含 **Alpha 通道**
  * **透明区域（alpha = 0）** 为待重绘区域；**不透明区域** 保持原图内容不变
  * 尺寸须与 `image_urls` 中第一张参考图完全一致
</ParamField>

<ParamField body="size" type="string">
  输出图像宽高比。默认值：`"1024x1024"`，也可传 `"auto"`：

  1K ：1:1=1024x1024,  9:16=720x1280,  16:9=1280x720, 3:2=1248x832,

  2K：1:1=2048x2048, 9:16=1440x2560, 16:9=2560x1440, 3:2=2496x1664, 4:3=2304x1728, 3:4=1728x2304, 2:3=1664x2496，

  4K：9:16=2160x3840, 16:9=3840x2160，
</ParamField>

<ParamField body="quality" type="string">
  图片质量。默认值：`"high"`。

  * `low` — 快速省成本，适合草稿预览
  * `medium` — 平衡速度与质量
  * `high` — 最高精度（默认）
</ParamField>

<ParamField body="output_format" type="string">
  输出文件格式。默认值：`"png"`。支持 `"png"` / `"jpeg"`。

  注意：不支持 `"webp"` 格式（Azure OpenAI 后端限制）。
</ParamField>

<Note>
  **遮罩图格式要求**：`mask_url` 指向的图片必须是含 Alpha 通道的 PNG 文件。透明像素（alpha = 0）标记为重绘区域，不透明像素标记为保留区域。遮罩尺寸必须与第一张参考图的原始尺寸完全匹配。
</Note>

***

## 代码示例

<CodeGroup>
  ```bash cURL（图生图·多参考图融合） theme={null}
  curl --request POST \
    --url https://geekapis.com/v1/images/generations \
    --header "Authorization: Bearer YOUR_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
      "model": "gpt-image-2",
      "prompt": "将两张参考图融合成赛博朋克风格插画海报",
      "image_urls": [
        "https://upload.wikimedia.org/wikipedia/commons/thumb/a/a9/Example.jpg/320px-Example.jpg",
        "https://upload.wikimedia.org/wikipedia/commons/thumb/4/47/PNG_transparency_demonstration_1.png/320px-PNG_transparency_demonstration_1.png"
      ],
      "size": "1024x1024",
      "quality": "high",
      "n": 1
    }' 
  ```

  ```bash cURL（局部重绘） theme={null}
  curl --request POST \
    --url https://geekapis.com/v1/images/generations \
    --header "Authorization: Bearer YOUR_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
      "model": "gpt-image-2",
      "prompt": "把背景换成星空，保持主体人物不变",
      "image_urls": [
        "https://placehold.co/320x320/png"
      ],
      "mask_url": "https://dummyimage.com/320x320/00000000/ffffff.png",
      "size": "1024x1024",
      "quality": "high",
      "output_format": "png"
    }'
  ```

  ```bash cURL（风格迁移·高清输出） theme={null}
  curl --request POST \
    --url https://geekapis.com/v1/images/generations \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "gpt-image-2",
      "prompt": "将此参考图片转换为日式水彩插画风格，保留构图和色调",
      "image_urls": [
        "https://example.com/photo.jpg"
      ],
      "size": "2496x1664",
      "resolution": "2K",
      "quality": "high",
      "output_format": "png"
    }'
  ```
</CodeGroup>

***

## 响应示例

```json 200 OK theme={null}
{
  "case": "多参考图融合",
  "status": 200,
  "reason": "OK",
  "created": 1782378514,
  "model": "firefly-gpt-image-2k-1x1",
  "data_count": 1,
  "revised_prompt": "将两张参考图融合成赛博朋克风格插画海报",
  "b64_prefix": "iVBORw0KGgoAAAANSUhEUgAABAAAAAQACAYAAAB/HSuDAAEAAElEQVR4nHT9acxu25bfhf3GnHOt9TRv",
  "b64_length": 2727452
}
```

***