> ## Documentation Index
> Fetch the complete documentation index at: https://quwan-b8010aef.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI 图片生成 / 编辑示例

> 使用 OpenAI 兼容接口（GPT Image 2.5 / gpt-image-2 / gpt-image-1 系列）生成与编辑图片的完整示例

# OpenAI 图片生成 / 编辑

本页覆盖两种能力：

* **文生图** `POST /v1/images/generations`
* **图生图 / 编辑** `POST /v1/images/edits`

两者都走 OpenAI 兼容协议。新接入推荐使用 `gpt-image-2.5-flare` 或 `gpt-image-2.5-sunburst`；已有业务仍可继续使用 `gpt-image-2-2026-04-21`、`gpt-image-1` / `gpt-image-1.5`。

## 接口与传图方式速查

| 场景 | Endpoint | Content-Type | 图片字段怎么传 | 是否支持多图 | 是否支持 mask |
| - | - | - | - | - | - |
| 文生图 | `/v1/images/generations` | `application/json` | 不传 `image` | - | 否 |
| 图片编辑（本地文件） | `/v1/images/edits` | `multipart/form-data` | `image=@original.png`；多图时重复传 `image` | 是，最多 16 张 | 是，`mask=@mask.png` |
| 图片编辑（URL / Base64） | `/v1/images/edits` | `application/json` | `image` 传字符串数组；每项可为 URL、纯 Base64 或 Data URI | 是，最多 16 张 | 是，`mask` 传单个字符串 |
| 统一生成入口（平台扩展） | `/v1/images/generations` | `application/json` | 增加 `image`，传单个字符串或字符串数组；平台按图片编辑处理 | 是，最多 16 张 | 否 |

> [!NOTE]
>
> OpenAI 标准的图片编辑使用 `multipart/form-data`。为方便服务端直接传 URL 或 Base64，平台额外支持 JSON body；不需要先把远程图片下载成本地文件。

## GPT Image 2.5（推荐）

平台提供两个独立模型名，请按场景明确选择，不要使用 `gpt-image-2.5` 作为模型名：

| 模型 | 推荐场景 | 图片编辑精度 |
| - | - | - |
| `gpt-image-2.5-flare` | 低延迟生成、批量创意探索 | 不支持 `input_fidelity=high` |
| `gpt-image-2.5-sunburst` | 精细编辑、主体和细节保持 | 编辑时支持 `input_fidelity=high` |

两个模型都支持 `low`、`medium`、`high`、`xhigh`、`max` 和 `auto` 六档质量。当前平台接入支持 PNG 和 JPEG 输出；WebP 暂不支持。

### 文生图

```bash cURL theme={null}
curl -X POST "https://api.tokenops.ai/v1/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API-KEY>" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "A small red paper boat floating on a calm white background",
    "size": "1024x1024",
    "quality": "low",
    "output_format": "png",
    "response_format": "b64_json"
  }'
```

### 图片编辑

精细编辑推荐使用 Sunburst。图片编辑同时支持 `multipart/form-data` 和 `application/json`。

#### multipart/form-data：上传本地图片

以下示例上传本地图片并要求以 JPEG 返回：

```bash cURL theme={null}
curl -X POST "https://api.tokenops.ai/v1/images/edits" \
  -H "Authorization: Bearer <API-KEY>" \
  -F model="gpt-image-2.5-sunburst" \
  -F image="@original.png" \
  -F prompt="保留主体构图，将画面转换为干净的水彩海报" \
  -F size="1024x1024" \
  -F quality="medium" \
  -F input_fidelity="high" \
  -F output_format="jpeg" \
  -F output_compression="80" \
  -F response_format="url"
```

#### application/json：传入 URL 或 Base64

JSON 请求中的 `image` 是字符串数组，每个元素可以是 HTTP(S) URL、纯 Base64，或带 `data:image/...;base64,` 前缀的 Base64。即使只有一张图片也需要使用数组。可选的 `mask` 是单个 URL 或 Base64 字符串。

```bash cURL theme={null}
curl -X POST "https://api.tokenops.ai/v1/images/edits" \
  -H "Authorization: Bearer <API-KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst",
    "prompt": "保留主体构图，将画面转换为干净的水彩海报",
    "image": [
      "https://example.com/original.png"
    ],
    "size": "1024x1024",
    "quality": "medium",
    "input_fidelity": "high",
    "output_format": "jpeg",
    "output_compression": 80,
    "response_format": "url"
  }'
```

如需局部编辑，可在 JSON body 中增加 `"mask": "https://example.com/mask.png"`。使用 Base64 时，建议避免在日志中记录完整字符串。

> [!WARNING]
>
> `input_fidelity=high` 仅用于 `gpt-image-2.5-sunburst`。向 `gpt-image-2.5-flare` 传该值会返回 HTTP 400。

> [!NOTE]
>
> `response_format` 是平台返回格式：`b64_json`（默认）直接返回图片 Base64；`url` 会先转存到平台云存储，再返回签名 URL。它不影响模型生成的 token 用量。

### GPT Image 2.5 参数

| 参数 | 类型 | 必填 | generations | edits | 默认值 / 可选值 | 说明 |
| - | - | -: | :-: | :-: | - | - |
| `model` | string | 是 | ✓ | ✓ | `gpt-image-2.5-flare` / `gpt-image-2.5-sunburst` | Flare 偏速度，Sunburst 偏编辑精度 |
| `prompt` | string | 是 | ✓ | ✓ | 最长 32000 字符 | 描述要生成的画面或对输入图的修改要求 |
| `image` | file / file\[]；string / string\[] | edits 是 | 扩展支持 | ✓ | 最多 16 张 | form-data 传文件；`edits` 的 JSON body 必须传字符串数组；`generations` 扩展兼容单个字符串或数组。内容可为 URL、纯 Base64 或 Data URI |
| `mask` | file 或 string | 否 | - | ✓ | PNG | 透明区域表示需要编辑的位置；尺寸须与第一张输入图一致 |
| `n` | integer | 否 | ✓ | ✓ | GPT Image 2.5 当前为 `1` | 同步接口每次返回一张图片 |
| `size` | string | 否 | ✓ | ✓ | `auto`；推荐 `1024x1024` / `1536x1024` / `1024x1536` | 不支持的自定义尺寸返回 HTTP 400 |
| `quality` | string | 否 | ✓ | ✓ | `auto` / `low` / `medium` / `high` / `xhigh` / `max` | 档位越高，通常耗时、输出 token 和费用越高 |
| `output_format` | string | 否 | ✓ | ✓ | `png`（默认）/ `jpeg` | 当前平台接入暂不支持 `webp` |
| `output_compression` | integer | 否 | ✓ | ✓ | `0`～`100` | 当前仅对 `output_format=jpeg` 生效 |
| `background` | string | 否 | ✓ | ✓ | `auto` / `opaque` / `transparent` | 透明背景请配合 `output_format=png` |
| `moderation` | string | 否 | ✓ | ✓ | `auto`（默认）/ `low` | 内容审核强度 |
| `input_fidelity` | string | 否 | - | ✓ | `high` | 仅 `gpt-image-2.5-sunburst` 支持；Flare 请省略 |
| `response_format` | string | 否 | ✓ | ✓ | `b64_json`（默认）/ `url` | `url` 为平台转存后返回的签名 URL |
| `user` | string | 否 | ✓ | ✓ | - | 业务侧最终用户标识，便于审计 |

同步文生图每次返回一张图片。建议优先使用表格中的标准尺寸；其他自定义尺寸是否可用以接口实际校验结果为准，不支持的尺寸会返回 HTTP 400。

### 响应与计费

```json theme={null}
{
  "created": 1776840564,
  "data": [
    {
      "b64_json": "<base64-encoded image>"
    }
  ],
  "usage": {
    "input_tokens": 17,
    "output_tokens": 196,
    "total_tokens": 213,
    "input_tokens_details": {
      "text_tokens": 17,
      "image_tokens": 0
    },
    "output_tokens_details": {
      "image_tokens": 196,
      "text_tokens": 0
    }
  },
  "generate_image": 1
}
```

#### 返回字段矩阵

| 字段路径 | 类型 | 是否一定返回 | 出现条件 / 含义 | 与计费的关系 |
| - | - | :-: | - | - |
| `created` | integer | 是 | 图片创建时间，Unix 秒级时间戳 | 无 |
| `data` | array | 是 | 生成结果列表；GPT Image 2.5 同步接口当前包含 1 项 | 无 |
| `data[].b64_json` | string | 条件 | `response_format=b64_json` 或未传时返回的图片 Base64 | 无；只影响交付方式 |
| `data[].url` | string | 条件 | `response_format=url` 时由平台转存并返回签名 URL | 无；只影响交付方式，URL 会过期 |
| `data[].revised_prompt` | string | 条件 | 上游返回的修订后提示词，主要用于 DALL·E 3；GPT Image 2.5 通常不返回 | 无 |
| `background` | string | 条件 | OpenAI 兼容保留字段；上游可能回传 `transparent` / `opaque` | 无；当前 Azure / QNAIGC GPT Image 2.5 适配器不返回 |
| `output_format` | string | 条件 | OpenAI 兼容保留字段，表示实际上游输出格式 | 无；当前 Azure / QNAIGC GPT Image 2.5 适配器不返回 |
| `quality` | string | 条件 | OpenAI 兼容保留字段，表示实际质量档位 | 会影响图片输出 token 数及费用；当前 Azure / QNAIGC GPT Image 2.5 适配器不返回 |
| `size` | string | 条件 | OpenAI 兼容保留字段，表示实际尺寸，例如 `1024x1024` | 会影响图片输出 token 数及费用；当前 Azure / QNAIGC GPT Image 2.5 适配器不返回 |
| `usage` | object | 条件 | GPT Image 模型的 token 用量；仅在上游提供 usage 时出现 | 计费依据 |
| `usage.input_tokens` | integer | 条件 | 文本与图片输入 token 合计 | 输入计费合计依据 |
| `usage.input_tokens_details.text_tokens` | integer | 条件 | 提示词等文本输入 token | 按文本输入单价计费 |
| `usage.input_tokens_details.image_tokens` | integer | 条件 | 图片编辑场景的输入图片 token；以渠道实际上报为准 | 按图片输入单价计费 |
| `usage.output_tokens` | integer | 条件 | 模型生成的输出 token 合计 | 输出计费合计依据 |
| `usage.output_tokens_details.image_tokens` | integer | 条件 | 图片输出 token | 按图片输出单价计费 |
| `usage.output_tokens_details.text_tokens` | integer | 条件 | 输出文本 token；GPT Image 2.5 纯图片响应通常为 `0` 或省略 | GPT Image 2.5 不产生计费文本输出 |
| `usage.total_tokens` | integer | 条件 | 输入与输出 token 总计，通常等于 `input_tokens + output_tokens` | 汇总展示；不要与明细重复计费 |
| `generate_image` | integer | 条件 | 平台扩展字段，表示本次成功生成的图片张数 | 不是 token，不要加到 `total_tokens` |
| `generate_image_r1` / `generate_image_r2` | integer | 条件 | 平台扩展的分辨率档位图片数，仅部分按张/档位计费的模型返回 | GPT Image 2.5 按 token 计费时通常省略 |

> [!WARNING]
>
> `b64_json` 与 `url` 按 `response_format` 二选一，不应假设两者同时存在。所有标记为“条件”的字段都应使用可选字段方式解析；字段缺失不等于数值为 `0`。

响应会保留模型返回的 `usage` token 总量与输入/输出明细。这两个模型分别按文本输入 token、图片输入 token 和图片输出 token 计费；缓存命中时使用对应的缓存输入计费项。当前 Images API 响应没有稳定约定 `cached_tokens` 返回字段，客户端不应通过重复请求或费用差额自行推断是否命中缓存。具体单价、币种、折扣和舍入规则以模型广场展示及实际账单为准，不要根据本页示例数字直接推算最终扣费。

## 图片生成（文生图）

**Content-Type 仅支持 `application/json`**。`multipart/form-data` 会被拒绝。

> [!TIP]
>
> **本接口也能做图生图**：在 body 里加 `image` 字段（URL 或 base64 字符串数组）即可，平台会自动等效转发到 `/v1/images/edits`。适合业务方用一个接口统一管理所有图片生成能力（不想区分"文生图 / 图生图"两个 endpoint 时）。适用于 `gpt-image-2.5-flare`、`gpt-image-2.5-sunburst`、`gpt-image-2` 和 `gpt-image-1` 家族。详见下方 [图片编辑 - 方式 C](#方式-c%EF%BC%9Av1-images-generations--image-字段平台扩展)。

### 快速开始

只需替换 `<API-KEY>` 为你的实际 API Key。

```bash cURL theme={null}
curl -X POST "https://api.tokenops.ai/v1/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API-KEY>" \
  -d '{
    "model": "gpt-image-2-2026-04-21",
    "prompt": "一只可爱的小猫在花园里玩耍，阳光明媚，油画风格",
    "n": 1,
    "size": "1024x1024",
    "quality": "medium"
  }'
```

```python Python theme={null}
import requests
import base64
from PIL import Image
from io import BytesIO

API_KEY = "<API-KEY>"
BASE_URL = "https://api.tokenops.ai/v1"

def generate_image(prompt, size="1024x1024", quality="medium", n=1,
                   model="gpt-image-2-2026-04-21"):
    url = f"{BASE_URL}/images/generations"
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {API_KEY}",
    }
    data = {
        "model": model,
        "prompt": prompt,
        "n": n,
        "size": size,        # 1024x1024 / 1536x1024 / 1024x1536
        "quality": quality,  # low / medium / high
        "response_format": "b64_json",  # 或 "url"
    }
    resp = requests.post(url, headers=headers, json=data)
    resp.raise_for_status()
    result = resp.json()

    images = []
    for i, img in enumerate(result["data"]):
        if img.get("b64_json"):
            image = Image.open(BytesIO(base64.b64decode(img["b64_json"])))
            filename = f"generated_{i+1}.png"
            image.save(filename)
            images.append(filename)
            print(f"图片已保存: {filename}")
        elif img.get("url"):
            images.append(img["url"])
            print(f"图片 URL: {img['url']}")
    return images


if __name__ == "__main__":
    generate_image("一只可爱的小猫在花园里玩耍，阳光明媚，油画风格")
```

```javascript JavaScript/Node.js theme={null}
import axios from "axios";
import fs from "fs";

const API_KEY = "<API-KEY>";
const BASE_URL = "https://api.tokenops.ai/v1";

async function generateImage(prompt, {
  size = "1024x1024",
  quality = "medium",
  n = 1,
  model = "gpt-image-2-2026-04-21",
} = {}) {
  const resp = await axios.post(`${BASE_URL}/images/generations`, {
    model, prompt, n, size, quality,
    response_format: "b64_json",
  }, {
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${API_KEY}`,
    },
  });

  return resp.data.data.map((img, i) => {
    if (img.b64_json) {
      const file = `generated_${i + 1}.png`;
      fs.writeFileSync(file, Buffer.from(img.b64_json, "base64"));
      console.log(`图片已保存: ${file}`);
      return file;
    }
    return img.url;
  });
}

generateImage("一只可爱的小猫在花园里玩耍，阳光明媚，油画风格");
```

## 图片编辑（图生图）

基于一张或多张参考图 + 可选 mask + prompt，生成编辑后的图片。

**两种 Content-Type 都支持**，按需选择：

* `multipart/form-data`：传统 OpenAI 兼容写法，直接上传本地文件
* `application/json`：平台扩展写法，`image` / `mask` 字段传 **URL** 或 **base64 字符串**（业务端接入更方便，不用 form-data 库）

### 方式 A：multipart/form-data

```bash cURL theme={null}
curl -X POST "https://api.tokenops.ai/v1/images/edits" \
  -H "Authorization: Bearer <API-KEY>" \
  -F model="gpt-image-2-2026-04-21" \
  -F image="@original.png" \
  -F mask="@mask.png" \
  -F prompt="把中间的区域换成一朵盛开的樱花" \
  -F n=1 \
  -F size="1024x1024" \
  -F quality="medium"
```

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

API_KEY = "<API-KEY>"
BASE_URL = "https://api.tokenops.ai/v1"

def edit_image(image_path, prompt, mask_path=None,
               size="1024x1024", quality="medium", n=1,
               model="gpt-image-2-2026-04-21"):
    url = f"{BASE_URL}/images/edits"
    headers = {"Authorization": f"Bearer {API_KEY}"}

    files = {"image": ("image.png", open(image_path, "rb"), "image/png")}
    if mask_path:
        files["mask"] = ("mask.png", open(mask_path, "rb"), "image/png")
    data = {
        "model": model,
        "prompt": prompt,
        "n": n,
        "size": size,
        "quality": quality,
        "response_format": "url",  # 或 "b64_json"
    }

    resp = requests.post(url, headers=headers, files=files, data=data)
    resp.raise_for_status()
    return resp.json()["data"]


if __name__ == "__main__":
    result = edit_image("original.png", "把中间的区域换成一朵盛开的樱花", mask_path="mask.png")
    for i, img in enumerate(result):
        print(f"编辑图 {i+1}: {img.get('url') or '[b64_json]'}")
```

```javascript JavaScript/Node.js theme={null}
import axios from "axios";
import FormData from "form-data";
import fs from "fs";

const API_KEY = "<API-KEY>";
const BASE_URL = "https://api.tokenops.ai/v1";

async function editImage(imagePath, prompt, {
  maskPath,
  size = "1024x1024",
  quality = "medium",
  n = 1,
  model = "gpt-image-2-2026-04-21",
} = {}) {
  const form = new FormData();
  form.append("model", model);
  form.append("prompt", prompt);
  form.append("n", String(n));
  form.append("size", size);
  form.append("quality", quality);
  form.append("response_format", "url");
  form.append("image", fs.createReadStream(imagePath));
  if (maskPath) form.append("mask", fs.createReadStream(maskPath));

  const resp = await axios.post(`${BASE_URL}/images/edits`, form, {
    headers: { Authorization: `Bearer ${API_KEY}`, ...form.getHeaders() },
  });
  return resp.data.data;
}
```

### 方式 B：application/json（推荐，接入更简单）

`image` 是**字符串数组**，每个元素可以是 `http(s)://` URL、纯 Base64，或带 `data:image/...;base64,` 前缀的 Base64。`mask` 是单个字符串，同样规则。平台会自动下载 / 解码，再透传到底层模型。

```bash cURL theme={null}
curl -X POST "https://api.tokenops.ai/v1/images/edits" \
  -H "Authorization: Bearer <API-KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2-2026-04-21",
    "prompt": "把中间的区域换成一朵盛开的樱花",
    "size": "1024x1024",
    "quality": "medium",
    "n": 1,
    "image": [
      "https://example.com/original.png"
    ],
    "mask": "https://example.com/mask.png"
  }'
```

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

API_KEY = "<API-KEY>"
BASE_URL = "https://api.tokenops.ai/v1"

def edit_image_json(image_inputs, prompt, mask=None,
                    size="1024x1024", quality="medium", n=1,
                    model="gpt-image-2-2026-04-21"):
    """
    image_inputs: list[str]，每个元素是 URL 或 base64
    mask:         str，URL 或 base64（可选）
    """
    url = f"{BASE_URL}/images/edits"
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    }
    data = {
        "model": model,
        "prompt": prompt,
        "n": n,
        "size": size,
        "quality": quality,
        "response_format": "url",
        "image": image_inputs,
    }
    if mask:
        data["mask"] = mask

    resp = requests.post(url, headers=headers, json=data)
    resp.raise_for_status()
    return resp.json()["data"]


if __name__ == "__main__":
    # URL 方式
    r1 = edit_image_json(["https://example.com/a.png"], "加上一顶草帽")

    # base64 方式（本地文件读出后编码）
    with open("local.png", "rb") as f:
        b64 = base64.b64encode(f.read()).decode()
    r2 = edit_image_json([b64], "换成油画风格")
```

```javascript JavaScript/Node.js theme={null}
import axios from "axios";
import fs from "fs";

const API_KEY = "<API-KEY>";
const BASE_URL = "https://api.tokenops.ai/v1";

async function editImageJson(imageInputs, prompt, {
  mask,
  size = "1024x1024",
  quality = "medium",
  n = 1,
  model = "gpt-image-2-2026-04-21",
} = {}) {
  const body = {
    model, prompt, n, size, quality,
    response_format: "url",
    image: imageInputs,
    ...(mask ? { mask } : {}),
  };
  const resp = await axios.post(`${BASE_URL}/images/edits`, body, {
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
  });
  return resp.data.data;
}

// URL 方式
await editImageJson(["https://example.com/a.png"], "加上一顶草帽");

// base64 方式
const b64 = fs.readFileSync("local.png").toString("base64");
await editImageJson([b64], "换成油画风格");
```

### 方式 C：`/v1/images/generations` + `image` 字段（平台扩展）

和方式 B 效果完全等价，但 endpoint 是 `/v1/images/generations`。用途是**让业务方用同一个 endpoint 覆盖"文生图 + 图生图"两种用法**（参考 `doubao-seedream` 的接口风格）：传 `image` 字段就是图生图，不传就是文生图。平台会在 provider 层自动把带 `image` 的 generations 请求转发到 edits 实现。

```bash cURL theme={null}
curl -X POST "https://api.tokenops.ai/v1/images/generations" \
  -H "Authorization: Bearer <API-KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2-2026-04-21",
    "prompt": "把苹果变成蓝色",
    "size": "1024x1024",
    "quality": "low",
    "image": [
      "https://example.com/apple.png"
    ]
  }'
```

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

API_KEY = "<API-KEY>"

# URL 方式
r = requests.post(
    "https://api.tokenops.ai/v1/images/generations",
    headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"},
    json={
        "model": "gpt-image-2-2026-04-21",
        "prompt": "把苹果变成蓝色",
        "image": ["https://example.com/apple.png"],
        "size": "1024x1024",
        "quality": "low",
    },
)
print(r.json())

# base64 方式
with open("apple.png", "rb") as f:
    b64 = base64.b64encode(f.read()).decode()
r = requests.post(
    "https://api.tokenops.ai/v1/images/generations",
    headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"},
    json={
        "model": "gpt-image-2-2026-04-21",
        "prompt": "把苹果变成蓝色",
        "image": [b64],   # 也兼容带 "data:image/png;base64," 前缀的 Base64
        "size": "1024x1024",
        "quality": "low",
    },
)
```

> [!WARNING]
>
> **方式 C 的限制**：
>
> * 仅 `gpt-image-2.5-flare` / `gpt-image-2.5-sunburst`、`gpt-image-1` / `gpt-image-1-mini` / `gpt-image-1.5` / `gpt-image-2` + 各自日期快照生效，其他模型（如 `dall-e-3`）传 `image` 会被上游直接忽略，退化为纯文生图。
> * **不支持 mask**：`/v1/images/generations` 请求体没有 mask 字段。需要用 mask 精修的场景请用方式 A 或 B。
> * 用量计费和方式 B 一致（`input_tokens_details.image_tokens` 会出现），不会因为换了 endpoint 就免费。

## 支持的参数

### 共用参数（generations / edits）

| 参数 | 类型 | 说明 |
| - | - | - |
| `model` | string | 模型名。推荐 `gpt-image-2.5-flare`（速度优先）或 `gpt-image-2.5-sunburst`（编辑精度优先）。也支持 `gpt-image-2-2026-04-21`、`gpt-image-1` / `gpt-image-1.5` / `gpt-image-1-mini` |
| `prompt` | string | 文字描述，必填。GPT image 系列上限 **32000 字符**（`dall-e-3` 为 4000，`dall-e-2` 为 1000） |
| `n` | integer | 生成张数。GPT Image 2.5 同步接口当前固定返回 1 张；其他模型通常为 **1 \~ 10**，`dall-e-3` 仅支持 `n=1` |
| `size` | string \| `"auto"` | 生成图片的尺寸，格式为 `宽x高`（WIDTHxHEIGHT）。 **gpt-image-2 / gpt-image-2-2026-04-21**：支持任意分辨率，宽和高都必须是 16 的倍数，宽高比需在 `1:3` \~ `3:1` 之间，例如 `1536x864`。超过 `2560x1440` 的分辨率为实验性支持，最大支持到 `3840x2160`。同时还要满足模型当前的像素和单边限制（见下方[尺寸约束](#尺寸约束gpt-image-2)）。 **GPT 图像模型标准尺寸**：`1024x1024`（方）、`1536x1024`（横）、`1024x1536`（纵）均受支持；`auto` 仅在允许自动选尺寸的模型上可用。 **dall-e-2**：`256x256` / `512x512` / `1024x1024`。 **dall-e-3**：`1024x1024` / `1792x1024` / `1024x1792`。 不传则走模型默认。 |
| `quality` | string | GPT Image 2.5：`low` / `medium` / `high` / `xhigh` / `max` / `auto`；gpt-image-2：`low` / `medium` / `high`，不传走服务端默认 |
| `output_format` | string | 输出图片格式，GPT Image 2.5 当前平台接入支持 `png`（默认）/ `jpeg`，暂不支持 `webp`；其他 GPT image 模型以对应模型说明为准 |
| `output_compression` | integer | 输出压缩率 `0 ~ 100`。GPT Image 2.5 当前仅在 `output_format=jpeg` 时使用；不传走模型默认值 |
| `background` | string | GPT Image 2.5 支持 `auto` / `opaque` / `transparent`；透明背景请使用 `png` |
| `moderation` | string | 内容审核强度，**GPT image 系列专属**：`auto`（默认）/ `low` |
| `response_format` | string | `b64_json`（默认）或 `url`。后者会把图转存到云存储并返回签名 URL |
| `user` | string | 业务方用户标识，便于审计 |

### 图片输入参数（`edits` 必用；`generations` 的方式 C 也支持 `image`）

| 参数 | 类型 | 说明 |
| - | - | - |
| `image` | file / file\[]（form-data） string\[]（edits JSON） string / string\[]（generations JSON） | 参考图。`/v1/images/edits` 的 JSON body 即使单图也要传数组；form-data 下同名字段重复即可多图。GPT Image 2.5 与 `gpt-image-1/2` 家族在 `/v1/images/generations` 也支持此字段（见方式 C） |
| `mask` | file（form-data） string（JSON，URL 或 base64） | 可选 PNG mask（alpha 通道透明区域表示"编辑此处"），尺寸必须与 `image` 一致。**仅 `/v1/images/edits` 支持**，方式 C 不支持 |
| `input_fidelity` | string | 图片编辑保真度。当前 `high` 仅支持 `gpt-image-2.5-sunburst`；Flare 请求请省略该字段 |

**JSON body 下 Base64 字符串约定**：纯 Base64 和带 `data:image/...;base64,` 前缀的 Base64 均支持。

### 尺寸约束（gpt-image-2）

`gpt-image-2` / `gpt-image-2-2026-04-21` 支持任意 `宽x高` 分辨率，但必须同时满足以下约束：

* 宽和高都必须是 **16 的倍数**
* 宽高比需在 **`1:3` \~ `3:1`** 之间
* 单边 ≤ **3840px**
* 像素总量在 **655,360 \~ 8,294,400** 之间（即 ≤ 3840×2160）
* 超过 `2560x1440` 的分辨率为**实验性支持**，最大支持到 `3840x2160`
* 常用值：`1024x1024`（方）/ `1536x1024`（横）/ `1024x1536`（纵）/ `1536x864` 等
* 超出约束会被上游 **400** 拒绝

## 响应示例

```json theme={null}
{
  "created": 1776840564,
  "data": [
    {
      "url": "https://model-static.skyengine.com.cn/<uid>/images/20260422/generated_xxx.png?q-sign-algorithm=..."
    }
  ],
  "usage": {
    "input_tokens": 10,
    "output_tokens": 272,
    "total_tokens": 282,
    "input_tokens_details": { "text_tokens": 10, "image_tokens": 0 }
  }
}
```

* 当请求 `response_format=b64_json`（或不传），`data[i]` 里会是 `b64_json` 字段
* 当请求 `response_format=url`，服务端会把图上传到云存储并返回签名 URL
* GPT Image 2.5 的 `usage.input_tokens_details` 区分文本和图片输入，`usage.output_tokens_details.image_tokens` 表示图片输出 token；平台按模型广场对应计费项结算

## 常见问题

1. **quality 不要传 `auto`**：gpt-image-2 的 Azure 部署不接受，会返 HTTP 500。显式传 `low / medium / high`，或整个字段留空走服务端默认。
2. **不支持 `style` 参数**：`vivid / natural` 是 `dall-e-3` 专属；gpt-image-1/2 都不支持。
3. **不支持 `transparent` 背景**（gpt-image-2）：OpenAI 官方文档明确不支持透明背景。
4. **输入图片限制**（edits）：推荐 PNG，单文件 \< 20MB；多图场景时总量也有上限。
5. **耗时预期**：quality=low 约 20-30s，medium 约 60-80s，high 约 200s+。按 token 计费，high 耗费显著更高。
6. **返回的 URL 有签名过期时间**：如果业务侧需要长期保存，建议请求 `response_format=b64_json` 自行落库，或下载 URL 对应图片另存。

## 应用场景

| 场景 | 推荐 | 提示 |
| - | - | - |
| 广告 / 社媒配图 | generations, quality=medium | 多次生成选最优 |
| 产品原型可视化 | generations, size=1024x1024 | 描述要具体（品类 / 风格 / 视角） |
| 抠图 / 背景替换 | edits + mask | mask 边缘要干净，alpha=0 为"替换处" |
| 风格转换 | edits（不带 mask） | prompt 指明目标风格 |
| 多参考图合成 | edits 多 `image` | 按数组顺序上传，主体图放第一个 |


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