GPT-Image-2.5 生图接入

RootFlowAI 的 GPT-Image-2.5 通过 OpenAI 兼容的 Images API 接入，支持文生图、参考图生成、图生图和蒙版编辑。提供 Flare、Sunburst 两个系列，每个系列按分辨率分为三个计次模型；质量通过独立的 quality 参数选择。

首次接入建议使用 gpt-image-2.5-flare-count，从 1K 图片开始。需要透明素材时，显式设置 background: "transparent" 和 output_format: "png"，返回图片包含真实 Alpha 透明通道。

接入准备

1. 在 API Keys 创建令牌，选择 GPT 绘图计次 分组，并确保令牌允许调用所需模型。
2. 在运行环境设置 ROOTFLOWAI_API_KEY，值为你的本站 API Key。不要将 Key 写进源码、前端页面或公开仓库。
3. SDK 的 base_url / baseURL 设置为 https://api.rootflowai.com/v1。

认证请求头为 Authorization: Bearer <你的本站 API Key>。使用上述 SDK Base URL 时，不要再重复拼接 /v1。

可以先查询当前令牌的模型列表，这一步不会创建图片：

curl --fail-with-body https://api.rootflowai.com/v1/models \
  -H "Authorization: Bearer ${ROOTFLOWAI_API_KEY}"

模型与计费

请求必须填写表中的完整模型名。gpt-image-2.5 是系列名称，不能直接作为本站调用模型名；省略 -count 等后缀也不能调用。

不同分辨率模型分别定价，同一模型的 Low、Medium、High、Max、Xhigh 使用相同计次价格。具体价格以 模型价格页 和账户消费日志为准。响应中即使带有 usage，本页模型仍按次结算。

文生图

以下示例生成一张 1K、Medium 质量的商品图。生图属于付费请求，请先确认模型、参数和账户余额。

curl

curl --fail-with-body --max-time 600 \
  https://api.rootflowai.com/v1/images/generations \
  -H "Authorization: Bearer ${ROOTFLOWAI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare-count",
    "prompt": "一只白色陶瓷咖啡杯的商品主图，白色背景，柔和棚拍灯光，陶瓷纹理清晰，不要文字",
    "n": 1,
    "size": "1024x1024",
    "quality": "medium",
    "response_format": "url"
  }'

Python OpenAI SDK

先安装 openai 包，并设置环境变量 ROOTFLOWAI_API_KEY：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ROOTFLOWAI_API_KEY"],
    base_url="https://api.rootflowai.com/v1",
    timeout=600.0,
    max_retries=0,
)

result = client.images.generate(
    model="gpt-image-2.5-flare-count",
    prompt="一只白色陶瓷咖啡杯的商品主图，白色背景，柔和棚拍灯光，不要文字",
    n=1,
    size="1024x1024",
    quality="medium",
    response_format="url",
)

print(result.data[0].url)

本站扩展的质量、比例和参考图字段可能不在某些 SDK 的类型枚举中。遇到客户端参数校验限制时，可使用 HTTP JSON 请求，或 SDK 的 extra_body 传递扩展字段。

分辨率与画面比例

先通过模型名选择分辨率，再用 size 选择画面形状。改成 2K 时，需要同时将模型切换为 -hd-count；只把 1K 模型的 size 写成 2048x2048 会被拒绝。

size 有三种写法：

支持的比例为：1:1、16:9、9:16、4:3、3:4、3:2、2:3、5:4、4:5、2:1、1:2、21:9、9:21。由于像素对齐，实际比例可能有少量偏差。

图生图和参考图请求也遵循以上规则。省略 size 或设置 auto 不会自动继承参考图比例；需要保留横图或竖图构图时，请显式指定尺寸或比例。

五档质量与透明背景

quality 接受五个独立档位：

建议明确填写小写值。Max 和 Xhigh 是两个独立选项，不会被自动改为 High。质量不改变所选模型的分辨率档位，也不改变该模型的计次单价；较高档位可能需要更长等待时间。省略 quality 或填写 auto 时使用服务默认策略，不保证固定为某一档。

生成透明 PNG 的完整示例：

curl --fail-with-body --max-time 600 \
  https://api.rootflowai.com/v1/images/generations \
  -H "Authorization: Bearer ${ROOTFLOWAI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare-hd-count",
    "prompt": "一只完整的白色陶瓷咖啡杯，独立物体，干净轮廓，背景透明，不要地面、阴影背景或棋盘格",
    "n": 1,
    "size": "2048x2048",
    "quality": "high",
    "background": "transparent",
    "output_format": "png",
    "response_format": "url"
  }'

background 可选 auto、opaque、transparent；output_format 可选 png、jpeg、webp。当前透明输出实测使用 PNG，建议按上例设置。JPEG 不支持 Alpha 通道，不能与 transparent 一起使用。检查透明度时，应查看下载图片的 Alpha 通道，而不是仅凭预览中的白底或棋盘格判断。

参考图生成

在 /images/generations 的 JSON 中增加标准字段 image，值为数组，并在提示词中说明需要保留和修改的内容。数组元素可以是可公开读取的 HTTPS 图片 URL，或带 MIME 类型的 Data URI，例如 data:image/png;base64,...。

下面使用本地 reference.png 构造 Data URI，生成 2K、Xhigh 质量的修改图。先将需要编辑的图片放到脚本工作目录，并确认文件名与实际格式一致：

import base64
import os
from pathlib import Path
from openai import OpenAI

reference = Path("reference.png")
image_data = base64.b64encode(reference.read_bytes()).decode("ascii")

client = OpenAI(
    api_key=os.environ["ROOTFLOWAI_API_KEY"],
    base_url="https://api.rootflowai.com/v1",
    timeout=600.0,
    max_retries=0,
)

result = client.images.generate(
    model="gpt-image-2.5-flare-hd-count",
    prompt="以参考图中的商品为主体，保留外形、标志和主要构图，将包装上的红色丝带改为蓝色",
    n=1,
    response_format="url",
    extra_body={
        "image": [f"data:image/png;base64,{image_data}"],
        "size": "2048x2048",
        "quality": "xhigh",
    },
)

print(result.data[0].url)

使用网络参考图时，将 image 数组元素替换为实际图片 URL。链接需要直接返回图片，不能使用登录页面、分享页面或仅在内网可访问的地址。不要只把图片链接写进 prompt，也不要把字段改成 reference_images 等非标准名称。

接口可以解析多个参考图，但当前实际效果验收以单张参考图为主。多参考图的主体一致性、融合效果需要结合具体素材评估，建议先从单张开始。

图生图与蒙版编辑

本地文件可直接上传到 /images/edits，无需先上传到图床。下面将 reference.png 作为输入图片，生成 2K、Max 质量的编辑结果：

curl --fail-with-body --max-time 600 \
  https://api.rootflowai.com/v1/images/edits \
  -H "Authorization: Bearer ${ROOTFLOWAI_API_KEY}" \
  -F 'model=gpt-image-2.5-flare-hd-count' \
  -F 'prompt=保留商品的外形、标志和构图，将红色丝带改为蓝色' \
  -F 'image=@reference.png;type=image/png' \
  -F 'n=1' \
  -F 'size=2048x2048' \
  -F 'quality=max' \
  -F 'response_format=url'

使用 curl -F 时，让 curl 自动生成 Content-Type 和 multipart boundary，不要手动添加 Content-Type: application/json。

如需限定编辑区域，在上述请求中再添加一个表单字段：

-F 'mask=@mask.png;type=image/png'

请准备与输入图同尺寸、带 Alpha 通道的 PNG 蒙版：透明区域表示希望修改的区域，不透明区域表示希望保留的区域，并用 prompt 描述修改目标。蒙版用于指导生成式编辑，不保证未编辑区域逐像素不变。只做整体风格或背景修改时，可以省略 mask。

响应与图片保存

成功响应从 data[0].url 读取结果，结构如下；示例 URL 仅用于说明字段：

{
  "created": 1788912000,
  "data": [
    {
      "url": "https://cdn.rootflowai.com/images/example.png"
    }
  ]
}

图片 URL 可用于预览和下载，重要成品请及时保存到自己的素材库。响应也可能包含 usage，调用方不应依赖它一定存在。

本页模型返回 URL，不返回 b64_json。response_format 请省略或填写 url；如果应用需要 Base64，请在拿到 URL 后自行下载并编码。

限制与错误处理

图片生成是同步长请求。示例将客户端等待时间设为 600 秒，并关闭 SDK 自动重试；但客户端等待时间不会延长网关的等待上限，仍可能在约 300 秒收到网关超时。

超时只表示客户端未收到最终结果，不代表任务一定没有执行或一定未计费。不要配置无限重试，也不要在结果不明时立即重复提交。先到 消费日志 核对本次请求；仍无法判断时联系服务支持。

其他绘图模型的接入方式见 图像生成。