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

# GPT Image 編輯

> GPT Image 圖片編輯欄位、模型限制與請求示例。

使用 OpenAI Images 編輯請求格式，通過 GPT Image 編輯一張或多張圖片。

`POST https://api.mixroute.ai/v1/images/edits`

## 支援模型

| 模型 ID           | 能力與限制                 |
| --------------- | --------------------- |
| `gpt-image-2`   | 生成與編輯，支援靈活尺寸，輸入固定高保真。 |
| `gpt-image-1.5` | 生成與編輯，使用標準圖片尺寸。       |
| `gpt-image-1`   | 生成與編輯，使用標準圖片尺寸。       |

## 請求參數

| 欄位                   | 型別              | 必填 | 說明                                                                                |
| -------------------- | --------------- | -- | --------------------------------------------------------------------------------- |
| `model`              | string          | 是  | 使用上表完整模型 ID，顯式指定呼叫模型。                                                             |
| `prompt`             | string          | 是  | 生成或編輯指令，最多 32000 個字元。                                                             |
| `image`              | file \| file\[] | 是  | PNG、JPEG 或 WebP 輸入，單張小於 50 MB，最多 16 張。通過 multipart 表單上傳，多圖可重複使用 `image[]`。        |
| `mask`               | file            | 否  | PNG 蒙版，小於 4 MB，畫素尺寸須與第一張源圖一致。完全透明區域表示編輯區域；多圖請求只對第一張圖片應用蒙版。                        |
| `input_fidelity`     | string          | 否  | GPT Image 1 和 1.5 可使用 `high` 或 `low`；GPT Image 2 固定以高保真處理輸入，不傳此欄位。                |
| `n`                  | integer         | 否  | 輸出圖片數量，範圍 1-10，預設 1。                                                              |
| `size`               | string          | 否  | 輸出尺寸，或使用預設值 `auto`；具體規則見下方版本說明。                                                   |
| `quality`            | string          | 否  | `low`、`medium`、`high` 或預設值 `auto`。                                                |
| `background`         | string          | 否  | `auto`（預設）、`opaque` 或 `transparent`。透明背景須使用 PNG 或 WebP；GPT Image 2 的透明背景能力處於預覽階段。 |
| `output_format`      | string          | 否  | 輸出圖片編碼格式：`png`（預設）、`jpeg` 或 `webp`。                                               |
| `output_compression` | integer         | 否  | 壓縮設定，範圍 0-100，預設 100，僅用於 JPEG 或 WebP 輸出。                                          |
| `stream`             | boolean         | 否  | `true` 時以 SSE 返回結果，預設 `false`。                                                    |
| `partial_images`     | integer         | 否  | 流式響應中的中間圖片數量，範圍 0-3；為 0 時只返回最終圖片。生成提前完成時，中間圖片可能少於指定數量。                            |
| `user`               | string          | 否  | 用於濫用監測的穩定終端使用者標識，避免直接提供個人資訊。                                                      |

## 尺寸規則

| 模型                | 允許尺寸                                                                        |
| ----------------- | --------------------------------------------------------------------------- |
| GPT Image 1 / 1.5 | `auto`, `1024x1024`, `1536x1024`, `1024x1536`                               |
| GPT Image 2       | `auto` 或 `寬x高`。寬高均為 16 的倍數，單邊不超過 3840 px，長短邊比例不超過 3:1，總畫素數為 655360-8294400。 |

GPT Image 2 超過 3686400 總畫素的解析度屬於實驗性範圍。此處 GPT 模型返回 Base64 圖片資料，不傳 DALL-E 專用的 `response_format` 或 `style`。

<Info>
  使用 multipart/form-data，不使用 JSON 圖片 URL 物件；由 cURL 或 SDK 設定 multipart boundary。`input_fidelity=auto/medium` 和頂層 `images` JSON 陣列不屬於此 OpenAI 請求格式。
</Info>

## 呼叫示例

將 MixRoute Key 設定到環境變數 `MIXROUTE_API_KEY`，通過 `Authorization: Bearer ...` 認證。編輯圖片前，將素材佔位值替換為可訪問的圖片或本地檔案。

```bash theme={null}
curl --request POST "https://api.mixroute.ai/v1/images/edits" \
  --header "Authorization: Bearer $MIXROUTE_API_KEY" \
  --form "model=gpt-image-2" \
  --form "image[]=@source.png" \
  --form "prompt=Make the mug blue while preserving its shape, lighting, and background." \
  --form "size=1024x1024" \
  --form "quality=low" \
  --form "output_format=png"
```

### Python

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

client = OpenAI(api_key=os.environ["MIXROUTE_API_KEY"], base_url="https://api.mixroute.ai/v1")
with open("source.png", "rb") as source:
    result = client.images.edit(
        model="gpt-image-2",
        image=source,
        prompt="Make the mug blue while preserving its shape, lighting, and background.",
        size="1024x1024",
        quality="low",
        output_format="png",
    )
Path("edited.png").write_bytes(base64.b64decode(result.data[0].b64_json))
```

區域性編輯時增加 `mask` 檔案；多圖參考時增加圖片檔案，蒙版仍只作用於第一張圖。

## 響應

從 `data[].b64_json` 讀取圖片，並按請求的 `output_format` 解碼儲存。流式響應返回中間圖片和完成事件，最終檔案應使用完成事件中的資料。

[GPT Image 圖片生成](/zh-hant/api-reference/endpoint/gpt-image)