GPT Image 2.5

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

文生图

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"
  }'

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))

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"));

图生图

上传文件

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

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"

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))

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

传 URL

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

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"
  }'

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])

image_url 接受哪些值：

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

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

多张参考图

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

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"

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" }
    ]
  }'

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

蒙版编辑

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

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"

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" }
  }'

蒙版尺寸与原图不一致会报 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`

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
  }'

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}}

参数说明

文生图（`/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，且与源图同尺寸

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

响应结构

{
  "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'.`

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

API 参考

查看可交互的 API Playground。

快速开始

原生兼容端点

模型 API

参数怎么传

核心能力

输出规格

文生图

图生图

上传文件

传 URL

多张参考图

蒙版编辑

流式输出

参数说明

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

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

响应结构

限制与错误码

API 参考

​参数怎么传

​核心能力

​输出规格

​文生图

​图生图

​上传文件

​传 URL

​多张参考图

​蒙版编辑

​流式输出

​参数说明

​文生图（/v1/images/generations）

​图生图（/v1/images/edits）

​响应结构

​限制与错误码

API 参考

参数怎么传

核心能力

输出规格

文生图

图生图

上传文件

传 URL

多张参考图

蒙版编辑

流式输出

参数说明

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

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

响应结构

限制与错误码