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

# GPT Image

> 使用 gpt-image-2 生成和编辑图像，兼容 OpenAI Images API

> 更新日期：2026-06-06

# GPT Image

`gpt-image-2` 通过 OpenAI Images API 兼容路径调用：

```text theme={null}
POST /v1/images/generations
POST /v1/images/edits
```

<Warning>
  `gpt-image-2` 图片生成请求请优先使用主承接线路 `https://api.crazyrouter.com/v1`。完整生成端点为 `https://api.crazyrouter.com/v1/images/generations`。账号登录、充值和控制台仍使用 `https://crazyrouter.com`。
</Warning>

## 生成图像

### 请求参数

| 参数                   | 类型      | 必填 | 说明                                                                                                                   |
| -------------------- | ------- | -- | -------------------------------------------------------------------------------------------------------------------- |
| `model`              | string  | 是  | 固定为 `gpt-image-2`                                                                                                    |
| `prompt`             | string  | 是  | 图像描述提示词                                                                                                              |
| `n`                  | integer | 否  | 生成数量，默认 `1`，范围 `1-10`                                                                                                |
| `size`               | string  | 否  | `auto` 或 `宽x高`。宽高必须为 16 的倍数，单边不超过 3840，总像素在 655360 到 8294400 之间，长短边比例不超过 3:1。常用值：`1024x1024`、`1536x1024`、`1024x1536` |
| `quality`            | string  | 否  | `auto`、`low`、`medium`、`high`。兼容 `hd`，服务端会归一为 `high`；兼容 `standard`，服务端会归一为 `auto`                                     |
| `background`         | string  | 否  | `auto` 或 `opaque`。`gpt-image-2` 不支持 `transparent`                                                                    |
| `output_format`      | string  | 否  | `png`、`jpeg`、`webp`                                                                                                  |
| `output_compression` | integer | 否  | `0-100`，仅当 `output_format` 为 `jpeg` 或 `webp` 时可用                                                                     |
| `moderation`         | string  | 否  | `auto` 或 `low`                                                                                                       |
| `stream`             | boolean | 否  | 是否使用 SSE 流式响应                                                                                                        |
| `partial_images`     | integer | 否  | `0-3`，仅当 `stream=true` 时可用                                                                                           |
| `user`               | string  | 否  | 终端用户标识                                                                                                               |

为兼容旧 DALL-E / OpenAI Images 客户端，`gpt-image-2` 会接收 `response_format=url`、`response_format=b64_json`、`quality=standard` 和 `style=vivid/natural`。其中 `response_format` 和 `style` 不会透传给上游，`quality=standard` 会归一为 `auto`。

<Warning>
  `response_format` 只是 Crazyrouter 为旧客户端保留的兼容字段，不是 `gpt-image-2` 上游参数。新接入请优先使用 `output_format="png"`、`"jpeg"` 或 `"webp"` 控制图片文件格式，并默认读取响应里的 `data[0].url`。如果旧客户端传 `response_format="b64_json"`，服务端会尽量保留 base64 响应语义。
</Warning>

仍会被拒绝的参数组合包括：`input_fidelity`、`background=transparent`、`output_format=png` 搭配 `output_compression`。

### 请求示例

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.crazyrouter.com/v1/images/generations \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -d '{
      "model": "gpt-image-2",
      "prompt": "一只穿着宇航服的猫咪在月球上行走，背景是地球",
      "n": 1,
      "size": "1024x1024",
      "quality": "low",
      "output_format": "png"
    }'
  ```

  ```python Python theme={null}
  from openai import OpenAI

  client = OpenAI(
      api_key="YOUR_API_KEY",
      base_url="https://api.crazyrouter.com/v1",
  )

  response = client.images.generate(
      model="gpt-image-2",
      prompt="一只穿着宇航服的猫咪在月球上行走，背景是地球",
      n=1,
      size="1024x1024",
      quality="low",
      output_format="png",
  )

  print(response.data[0].url)
  ```
</CodeGroup>

### 流式生成

`gpt-image-2` 支持 `stream=true`。如果请求中包含 `partial_images`，必须同时开启 `stream`，且取值范围为 `0-3`。

```bash cURL theme={null}
curl -N -X POST https://api.crazyrouter.com/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一个蓝色极简验证图标，白色背景",
    "size": "1024x1024",
    "quality": "high",
    "stream": true,
    "partial_images": 2
  }'
```

<Note>
  `quality=high` 或兼容写法 `quality=hd` 的同步请求可能耗时较长。图片生成业务请优先走 `https://api.crazyrouter.com/v1`；高质量请求建议使用 `stream=true`，或确保客户端超时大于 180 秒。
</Note>

### 响应示例

```json theme={null}
{
  "created": 1778990000,
  "data": [
    {
      "url": "https://media.crazyrouter.com/task-artifacts/2026/05/17/sync-image/request-id-1.png"
    }
  ],
  "output_format": "png",
  "quality": "low",
  "size": "1024x1024"
}
```

***

## 编辑图像

```
POST /v1/images/edits
```

基于已有图像进行编辑，支持遮罩区域编辑，也支持传入多张参考图做融合、风格迁移或局部组合。

### 请求参数

| 参数                   | 类型             | 必填 | 说明                                                  |
| -------------------- | -------------- | -- | --------------------------------------------------- |
| `model`              | string         | 是  | 固定为 `gpt-image-2`                                   |
| `image` / `image[]`  | file 或 file\[] | 是  | 原始图片或参考图片文件（multipart）；`gpt-image-2` 最多支持 `16` 张参考图 |
| `prompt`             | string         | 是  | 编辑描述                                                |
| `mask`               | file           | 否  | 遮罩图片，透明区域为需要编辑的部分                                   |
| `n`                  | integer        | 否  | 生成数量，默认 `1`，范围 `1-10`                               |
| `size`               | string         | 否  | 同生成接口                                               |
| `quality`            | string         | 否  | `auto`、`low`、`medium`、`high`；`hd` 会归一为 `high`       |
| `background`         | string         | 否  | `auto` 或 `opaque`                                   |
| `output_format`      | string         | 否  | `png`、`jpeg`、`webp`                                 |
| `output_compression` | integer        | 否  | `0-100`，仅当 `output_format` 为 `jpeg` 或 `webp` 时可用    |
| `stream`             | boolean        | 否  | 是否使用 SSE 流式响应                                       |
| `partial_images`     | integer        | 否  | `0-3`，仅当 `stream=true` 时可用                          |

### 单图编辑示例

```python Python theme={null}
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.crazyrouter.com/v1",
)

response = client.images.edit(
    model="gpt-image-2",
    image=open("original.png", "rb"),
    mask=open("mask.png", "rb"),
    prompt="在天空中添加一道彩虹",
    n=1,
    size="1024x1024",
    quality="low",
)

print(response.data[0].url)
```

### 多图参考编辑示例

多图编辑请求必须使用 `multipart/form-data`。推荐用多个 `image[]` 字段传参考图；服务端也兼容重复的 `image` 字段。

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.crazyrouter.com/v1/images/edits \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -F "model=gpt-image-2" \
    -F "prompt=把第一张图的人物与第二张图的背景融合成一张自然的宣传图" \
    -F "size=1024x1024" \
    -F "quality=low" \
    -F "n=1" \
    -F "image[]=@person.png" \
    -F "image[]=@background.png"
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.crazyrouter.com/v1/images/edits",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      data={
          "model": "gpt-image-2",
          "prompt": "把第一张图的人物与第二张图的背景融合成一张自然的宣传图",
          "size": "1024x1024",
          "quality": "low",
          "n": "1",
      },
      files=[
          ("image[]", ("person.png", open("person.png", "rb"), "image/png")),
          ("image[]", ("background.png", open("background.png", "rb"), "image/png")),
      ],
      timeout=240,
  )

  response.raise_for_status()
  print(response.json()["data"][0]["url"])
  ```
</CodeGroup>

<Note>
  `gpt-image-2` 多图参考最多支持 16 张图片。多图请求会优先路由到支持多图参考的官方 OpenAI 承载渠道。
</Note>