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

# GPT Image 2.5

> OpenAI GPT Image 2.5 图像模型，通过 Upmore 提供文生图与图生图（支持蒙版局部编辑、透明背景、最多 16 张输入图），灵活分辨率最高 4K。模型名：gpt-image-2.5-flare、gpt-image-2.5-sunburst。

GPT Image 2.5 是 OpenAI 的图像生成与编辑模型，通过 Upmore API 以两个等价模型名提供：`gpt-image-2.5-flare` 与 `gpt-image-2.5-sunburst`。两者参数、限制、返回结构完全一致，任选其一即可。

它由两个端点覆盖：

| 任务      | 端点                            | 请求格式                                       |
| ------- | ----------------------------- | ------------------------------------------ |
| 文生图     | `POST /v1/images/generations` | `application/json`                         |
| 图生图（编辑） | `POST /v1/images/edits`       | `multipart/form-data` 或 `application/json` |

## 参数怎么传

两个端点用的是**同一套参数**，区别只在端点和请求编码方式。

| 内容                                                                                           | 文生图                            | 图生图                                                    |
| -------------------------------------------------------------------------------------------- | ------------------------------ | ------------------------------------------------------ |
| 端点                                                                                           | `POST /v1/images/generations`  | `POST /v1/images/edits`                                |
| 编码                                                                                           | JSON body                      | `multipart/form-data` **或** JSON body                  |
| `prompt`、`size`、`quality`、`n`、`background`、`output_format`、`moderation`、`output_compression` | JSON 字段，原生 JSON 类型 —— `"n": 2` | multipart：表单字段，**值一律是字符串**（`-F "n=2"`）；JSON：正常 JSON 类型 |
| 输入图                                                                                          | 不用                             | multipart：文件字段 `image`；JSON：`images[].image_url`       |
| 蒙版                                                                                           | 不用                             | multipart：文件字段 `mask`；JSON：`mask.image_url`            |

图生图端点有两种可互换的传法，按你手上有什么选：

* **手上有图片字节**（本地文件，或从别的接口拿到的文件）→ 用 `multipart/form-data` 上传文件。
* **手上有 URL**（TOS、R2 等对象存储、CDN 链接，或内联 base64）→ 用 `application/json` 配 `images[].image_url`。

## 核心能力

* **文生图** — 根据自然语言提示词生成图像
* **图生图** — 用提示词编辑已有图片，可上传文件、也可传 URL
* **多张输入图** — 单次编辑最多 16 张参考图
* **蒙版编辑** — 通过蒙版把修改限制在指定区域
* **灵活分辨率** — 任意尺寸，最高 4K；不传 `size` 时由模型自行选择分辨率
* **透明背景** — `background: "transparent"`，适合产出抠图素材
* **批量生成** — 通过 `n` 单次最多生成 10 张
* **流式预览** — 渲染过程中即可拿到中间帧

## 输出规格

| 属性      | 值                                                       |
| ------- | ------------------------------------------------------- |
| 尺寸      | 灵活分辨率，如 `1024x1024`、`1536x1024`、`2048x2048`、`3840x2160` |
| 尺寸约束    | 边长须为 16 的倍数，宽高比 ≤ 3:1，总像素 655,360–8,294,400，最长边 3,840px |
| 默认尺寸    | 不传 `size` 时由模型选择（约 130 万像素）                             |
| 质量      | `low`（默认）、`medium`、`high`、`auto`                        |
| 格式      | `png`（默认）、`jpeg`                                        |
| 背景      | `opaque`（默认）、`transparent`、`auto`                       |
| 单次输出张数  | 1–10                                                    |
| 单次输入图张数 | 1–16                                                    |

## 文生图

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.upmore.net/v1/images/generations \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-image-2.5-flare",
      "prompt": "一只坐在黄昏雪林里的红狐，写实风格",
      "size": "1536x1024",
      "quality": "high"
    }'
  ```

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

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

  response = client.images.generate(
      model="gpt-image-2.5-flare",
      prompt="一只坐在黄昏雪林里的红狐，写实风格",
      size="1536x1024",
      quality="high"
  )

  # 接口始终返回 base64 数据，需要自行解码落盘。
  with open("fox.png", "wb") as f:
      f.write(base64.b64decode(response.data[0].b64_json))
  ```

  ```javascript Node.js theme={null}
  import OpenAI from "openai";
  import { writeFile } from "node:fs/promises";

  const client = new OpenAI({
    apiKey: process.env.UPMORE_API_KEY,
    baseURL: "https://api.upmore.net/v1",
  });

  const response = await client.images.generate({
    model: "gpt-image-2.5-flare",
    prompt: "一只坐在黄昏雪林里的红狐，写实风格",
    size: "1536x1024",
    quality: "high",
  });

  await writeFile("fox.png", Buffer.from(response.data[0].b64_json, "base64"));
  ```
</CodeGroup>

## 图生图

### 上传文件

把图 POST 到 `/v1/images/edits`，格式为 `multipart/form-data`：原图放在 `image` 文件字段，指令放在 `prompt` 表单字段，其余参数（`size`、`quality`、`n` 等）都作为普通表单字段、以字符串值传递。

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.upmore.net/v1/images/edits \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -F "model=gpt-image-2.5-flare" \
    -F "prompt=把狐狸的毛变成亮蓝色，并加上飘落的雪花" \
    -F "image=@fox.png;type=image/png" \
    -F "size=1024x1024" \
    -F "quality=high"
  ```

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

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

  with open("fox.png", "rb") as source:
      response = client.images.edit(
          model="gpt-image-2.5-flare",
          image=source,
          prompt="把狐狸的毛变成亮蓝色，并加上飘落的雪花",
          size="1024x1024",
          quality="high",
      )

  with open("fox-blue.png", "wb") as f:
      f.write(base64.b64decode(response.data[0].b64_json))
  ```
</CodeGroup>

<Warning>
  multipart 里的 `image` **必须是真实文件**。传 URL 字符串会被拒：`Invalid type for 'image': expected one of an array of files or file, but got a string instead.` 要用 URL 请改用下面的 JSON 形式。
</Warning>

### 传 URL

改用 `application/json`，把图片放进 `images` —— 一个对象数组，每个对象带 `image_url`。图片已经在某处可访问时（TOS、R2、CDN，或内联 `data:` URL）就用这种形式。

<CodeGroup>
  ```bash cURL — 公开 URL（TOS、R2、CDN） theme={null}
  curl https://api.upmore.net/v1/images/edits \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-image-2.5-flare",
      "prompt": "把狐狸的毛变成亮蓝色，并加上飘落的雪花",
      "images": [
        { "image_url": "https://your-bucket.tos-cn-beijing.volces.com/fox.png" }
      ],
      "size": "1024x1024",
      "quality": "high"
    }'
  ```

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

  with open("fox.png", "rb") as f:
      data_url = "data:image/png;base64," + base64.b64encode(f.read()).decode()

  response = requests.post(
      "https://api.upmore.net/v1/images/edits",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      json={
          "model": "gpt-image-2.5-flare",
          "prompt": "把狐狸的毛变成亮蓝色，并加上飘落的雪花",
          "images": [{"image_url": data_url}],
          "size": "1024x1024",
          "quality": "high",
      },
  )

  print(response.json()["data"][0]["b64_json"][:100])
  ```
</CodeGroup>

`image_url` 接受哪些值：

| 值                                             | 是否支持                                 |
| --------------------------------------------- | ------------------------------------ |
| `https://…` 公开 URL —— TOS、R2、CDN,或上游能访问到的任意主机 | 支持                                   |
| `data:image/png;base64,…` 内联数据                | 支持                                   |
| 有时效的预签名 URL                                   | 支持,只要请求处理时签名仍有效                      |
| `tos://bucket/key`                            | 不支持 —— 该 scheme 会被拒,请传 `https://` 地址 |
| 非公开地址(内网、仅 VPN 可达、需登录)                        | 不支持 —— URL 由上游主动抓取,必须公网可达            |

<Note>
  上游 schema 里还有 `image_url` 的替代项 `file_id`,但 Upmore 未开放文件上传接口,实际只能使用 `image_url`。
</Note>

### 多张参考图

单次请求最多 **16 张**输入图。multipart 用 `image[]` 重复文件字段，JSON 往 `images` 里多加几个对象。

<CodeGroup>
  ```bash cURL — multipart，两个文件 theme={null}
  curl https://api.upmore.net/v1/images/edits \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -F "model=gpt-image-2.5-sunburst" \
    -F "prompt=把第二张图里的黄色圆形放进第一张图" \
    -F "image[]=@fox.png;type=image/png" \
    -F "image[]=@logo.png;type=image/png"
  ```

  ```bash cURL — JSON，两个 URL theme={null}
  curl https://api.upmore.net/v1/images/edits \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-image-2.5-sunburst",
      "prompt": "把第二张图里的黄色圆形放进第一张图",
      "images": [
        { "image_url": "https://example.com/fox.png" },
        { "image_url": "https://example.com/logo.png" }
      ]
    }'
  ```
</CodeGroup>

每张输入图都会按自身分辨率计入 `usage.input_tokens_details.image_tokens` —— 1024×1024 的图约为 1,024 个 token。传 16 张就按 16 张计费。

## 蒙版编辑

传 `mask` 可把修改限制在指定区域。蒙版必须是**带 alpha 通道的 PNG**，且与原图像素尺寸完全一致：透明像素表示允许模型重绘的区域，不透明区域保持不变。

<CodeGroup>
  ```bash cURL — multipart theme={null}
  curl https://api.upmore.net/v1/images/edits \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -F "model=gpt-image-2.5-flare" \
    -F "prompt=一个发光的金色球体" \
    -F "image=@fox.png;type=image/png" \
    -F "mask=@mask.png;type=image/png"
  ```

  ```bash cURL — JSON theme={null}
  curl https://api.upmore.net/v1/images/edits \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-image-2.5-flare",
      "prompt": "一个发光的金色球体",
      "images": [{ "image_url": "https://example.com/fox.png" }],
      "mask": { "image_url": "https://example.com/mask.png" }
    }'
  ```
</CodeGroup>

蒙版尺寸与原图不一致会报 `Invalid mask image format - mask size does not match image size`；没有 alpha 通道会报 `Invalid mask image format - mask image missing alpha channel`。

## 流式输出

设置 `stream: true` 后返回 Server-Sent Events：先推送最多 `partial_images` 个预览帧，最后必定以 `completed` 事件给出成品图。如果不传 `partial_images`，或图片在预览帧生成完之前就已完成，你可能只会收到 `completed` 事件。

| 端点                       | 事件                                                            |
| ------------------------ | ------------------------------------------------------------- |
| `/v1/images/generations` | `image_generation.partial_image`、`image_generation.completed` |
| `/v1/images/edits`       | `image_edit.partial_image`、`image_edit.completed`             |

<CodeGroup>
  ```bash cURL theme={null}
  curl -N https://api.upmore.net/v1/images/generations \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-image-2.5-flare",
      "prompt": "木桌上的一把蓝色陶瓷茶壶",
      "size": "1024x1024",
      "stream": true,
      "partial_images": 2
    }'
  ```

  ```text 响应（截断） theme={null}
  event: image_generation.partial_image
  data: {"type":"image_generation.partial_image","partial_image_index":0,"b64_json":"iVBORw0KGgo...","size":"1024x1024","quality":"low","output_format":"png"}

  event: image_generation.completed
  data: {"type":"image_generation.completed","b64_json":"iVBORw0KGgo...","size":"1024x1024","usage":{"input_tokens":11,"output_tokens":196,"total_tokens":207}}
  ```
</CodeGroup>

## 参数说明

### 文生图（`/v1/images/generations`）

| 参数                   | 类型      | 必填 | 说明                                                                                      |
| -------------------- | ------- | -- | --------------------------------------------------------------------------------------- |
| `model`              | string  | 是  | `gpt-image-2.5-flare` 或 `gpt-image-2.5-sunburst`                                        |
| `prompt`             | string  | 是  | 图像描述文本                                                                                  |
| `n`                  | integer | 否  | 生成张数，1–10，默认 `1`                                                                        |
| `size`               | string  | 否  | `{宽}x{高}`。边长须为 16 的倍数，宽高比 ≤ 3:1，总像素 655,360–8,294,400，最长边 3,840px。不传则由模型自行选择（约 130 万像素） |
| `quality`            | string  | 否  | `low`、`medium`、`high`、`auto`，默认 `low`                                                   |
| `background`         | string  | 否  | `opaque`、`transparent`、`auto`，默认 `opaque`；用 `transparent` 时建议输出 `png`                   |
| `output_format`      | string  | 否  | `png`、`jpeg`，默认 `png`                                                                   |
| `output_compression` | integer | 否  | `jpeg` 输出的压缩级别（0–100）                                                                   |
| `moderation`         | string  | 否  | `auto` 或 `low`，默认 `auto`                                                                |
| `stream`             | boolean | 否  | 是否以 SSE 推送中间帧，默认 `false`                                                                |
| `partial_images`     | integer | 否  | `stream` 为 `true` 时请求的预览帧数量                                                             |

### 图生图（`/v1/images/edits`）

文生图的参数全部适用，另加：

| 参数       | 类型               | 必填             | 说明                                                                        |
| -------- | ---------------- | -------------- | ------------------------------------------------------------------------- |
| `image`  | file             | 仅 multipart，必填 | 原图。重复为 `image[]` 可传多张                                                     |
| `images` | array of objects | 仅 JSON，必填      | 源图数组 `[{"image_url": "…"}]`，1–16 项                                        |
| `mask`   | file 或 object    | 否              | 可编辑区域。multipart 用文件字段；JSON 用 `{"image_url": "…"}`。须为带 alpha 的 PNG，且与源图同尺寸 |

<Warning>
  不支持 `response_format` 与 `input_fidelity`。图像数据始终以 base64 形式返回在 `data[].b64_json` 中；`output_format` 不接受 `webp`。
</Warning>

## 响应结构

```json theme={null}
{
  "created": 1789103440,
  "background": "opaque",
  "output_format": "png",
  "quality": "low",
  "size": "1024x1024",
  "data": [
    { "b64_json": "iVBORw0KGgo..." }
  ],
  "usage": {
    "input_tokens": 1053,
    "input_tokens_details": { "image_tokens": 1024, "text_tokens": 29 },
    "output_tokens": 439,
    "output_tokens_details": { "image_tokens": 439, "text_tokens": 0 },
    "total_tokens": 1492
  }
}
```

图生图时，`usage.input_tokens_details.image_tokens` 会计入源图，因此相同尺寸与质量下比文生图更贵。

## 限制与错误码

不满足约束的请求会立即返回 HTTP 400，并给出明确原因：

| 触发条件                                   | 返回信息                                                                                             |
| -------------------------------------- | ------------------------------------------------------------------------------------------------ |
| 边长不是 16 的倍数                            | `Width and height must both be divisible by 16.`                                                 |
| 宽高比超过 3:1                              | `The maximum supported aspect ratio is 3:1.`                                                     |
| 总像素少于 655,360                          | `Requested resolution is below the current minimum pixel budget.`                                |
| 总像素超过 8,294,400                        | `Requested resolution exceeds the current pixel budget.`                                         |
| 单边超过 3,840px                           | `The longest edge must be less than or equal to 3840.`                                           |
| `n` 超出 1–10                            | `Invalid 'n': integer above maximum value. Expected a value <= 10`                               |
| 输入图超过 16 张                             | 上游返回 HTTP 500 —— 请把请求控制在 16 张以内                                                                  |
| `quality` 取值非法                         | `Supported values are: 'low', 'medium', 'high', and 'auto'.`                                     |
| `output_format: "webp"`                | `Supported values are: 'png' and 'jpeg'.`                                                        |
| multipart 的 `image` 传 URL 字符串          | `Invalid type for 'image': expected one of an array of files or file, but got a string instead.` |
| `image` / `images` 结构不对                | `Unknown parameter: 'image'. For application/json on /v1/images/edits, use 'images' (array).`    |
| `image_url` 用了 `tos://` 等非 HTTP scheme | `Invalid 'images[0].image_url'. Expected a valid URL, but got a value with an invalid format.`   |
| 蒙版尺寸与源图不一致                             | `Invalid mask image format - mask size does not match image size`                                |
| 蒙版没有 alpha 通道                          | `Invalid mask image format - mask image missing alpha channel`                                   |
| 缺少 prompt                              | `Missing required parameter: 'prompt'.`                                                          |

<Note>
  上游还会对提示词与图片的组合做安全审查。被拒时返回 `Your request was rejected by the safety system…` 并附带一个 Azure request ID；换一组输入重试通常即可通过，若持续被拒，该 ID 是提交 Azure 支持工单所需的信息。
</Note>

<Card title="API 参考" icon="code" href="/zh/api-reference/model-api/openai/gpt-image-2-5/generate">
  查看可交互的 API Playground。
</Card>