GPT Image 2.5

GPT Image 2.5 接受文本提示词和可选的参考图。提交一次，保存返回的任务 ID，然后查询该任务以获取生成完成的图像。它分为两个读取相同参数的模型：Flare 适合日常工作，Sunburst 适合最看重编辑精度的场景。

模型 ID

四个 ID 接受相同的参数。两个渠道的区别在于计费；当前价格见模型页。

快速示例

curl https://api.seedrouter.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "An amber glass bottle on a cream background, studio lighting",
    "size": "1024x1024",
    "quality": "low"
  }'

端点

POST https://api.seedrouter.ai/v1/images/generations

生成、参考图编辑和遮罩编辑都使用同一个端点。响应返回的是任务 ID，而不是生成完成的图像。请把 API 密钥保存在服务端代码中。

参数

尺寸规则

常用取值为 1024x1024、1536x1024 和 1024x1536。自定义尺寸必须同时满足以下全部规则：

• 宽和高都是 16 的倍数。
• 任一边长都不超过 3840 像素。
• 宽高比在 1:3 到 3:1 之间。
• 总面积在 655,360 到 8,294,400 像素之间（含端点）。

auto 表示由模型决定输出尺寸。不要把 16:9 这类宽高比作为 size 传入。

Playground 提供 Auto、比例和自定义三种控件。比例模式把宽高比与 1K、2K 或 4K 的像素预算预设组合起来，最终只提交换算后的 size。这些只是界面预设，不是独立的 API 参数：不要传 resolution 或 aspect_ratio。例如 16:9 + 4K 提交 size: "3840x2160"；9:16 + 4K 提交 "2160x3840"；1:1 + 2K 提交 "2048x2048"。取整和边长上限可能使所选档位的实际像素数变少。提交前会显示确切的尺寸。

OpenAI 将高于 2560×1440 的分辨率描述为实验性。在上述限制范围内它们会被接受；但更高的分辨率并不保证更好的细节。

质量档位

xhigh 和 max 是 GPT Image 2.5 新增的档位；GPT Image 2 最高只到 high。档位越高渲染耗时越长，在按 token 计费的 ID 上也会消耗更多输出 token。在 1024x1024 下实测，low、medium、high、xhigh 和 max 各渲染一次分别报告了 196、439、1,756、3,122 和 7,024 个输出 token。这些是实测样本而非保证值：用量还取决于尺寸和内容。

草稿阶段请使用 low，先对比结果再决定是否提高档位。auto 由模型自行选择，它并不保证某个特定档位或费用。

透明背景

GPT Image 2.5 支持透明背景。需要透明背景时，请设置 background: "transparent" 并使用 PNG。JPEG 不支持透明。压缩仅对 JPEG 生效。

user 可用于 API 集成，但不会在 Playground 中显示，也不会自动填充。

可选的标量设置（n、size、quality、background、output_format、output_compression、moderation）接受 null 表示省略。未知字段会被拒绝。input_fidelity 不是 GPT Image 2.5 的参数。style 和 response_format 属于其他图像模型，此处不接受。

模式

没有单独的模式参数，也没有另一个编辑端点需要选择。

编辑参考图

curl https://api.seedrouter.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "Make the bottle blue. Preserve the composition and lighting.",
    "images": [{"image_url": "https://example.com/reference.png"}],
    "mask": {"image_url": "https://example.com/mask.png"},
    "output_format": "jpeg",
    "output_compression": 90
  }'

请把示例中的两个 URL 替换成你自己的、可访问的图像。若不需要指定编辑区域，省略 mask 即为参考图编辑。

媒体输入

本 API 只接受 URL 引用。不接受 OpenAI Files ID、base64 data URL 和 multipart 上传。Playground 会先把所选文件上传到存储，再提交其 URL。

参考图必须是公开可访问的 HTTP(S) URL，指向 PNG、JPEG 或 WebP 文件，单个文件小于 50 MB。遮罩必须是小于 4 MB 的 PNG，尺寸与第一张参考图相同；其透明区域标记要编辑的部分。遮罩只是对模型的引导，并不保证像素级精确的边界。传入多张参考图时，遮罩作用于第一张。URL 媒体在处理过程中才会被校验；无效或无法访问的媒体会导致任务失败。

Playground 会上传所选文件并提交其 URL。API 请求使用 JSON 形式的 URL 对象：不要发送文件字节、base64、data: URL、blob: URL 或 multipart 表单数据。

计费维度

当前费率请查看模型定价部分。Standard ID 每交付一张图收一个固定价，与质量、尺寸和提示词无关。在 Official ID 上，最终费用取决于输入和输出的用量：质量、输出尺寸、参考图、提示词长度和出图数量都会影响它。

Playground 的预估基于实测样本和当前费率，不构成保证报价。最终扣费请在账号的用量记录中查看。失败的任务不计费。

输出结构

提交后返回一个任务引用：

{
  "id": "task_...",
  "model": "gpt-image-2.5-flare",
  "status": "processing",
  "created_at": 1789970508
}

轮询任务

curl https://api.seedrouter.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY"

请以较为克制的间隔轮询，例如每三秒一次，直到 status 变为 completed 或 failed。轮询过程中出现网络超时，并不意味着生成失败：请保留任务 ID 并继续查询。不要为了查看进度而再创建一个任务。

完整轮询示例

请在上面的 Python 提交示例之后运行这段代码。它使用返回的 task_id，最长等待十分钟。达到这个本地超时只会停止轮询；请保留 ID 并继续查询同一个任务。

import time

print(f"Task ID: {task_id}")
deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    result = requests.get(
        f"https://api.seedrouter.ai/v1/tasks/{task_id}",
        headers={"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"},
        timeout=30,
    )
    result.raise_for_status()
    task = result.json()
    if task["status"] == "completed":
        for image in task["output"]["data"]:
            print(image["url"])
        break
    if task["status"] == "failed":
        raise RuntimeError(task["error"]["message"])
    time.sleep(3)
else:
    raise TimeoutError(f"Still waiting. Resume polling task {task_id}.")

已完成的任务

已完成的任务会返回托管的图像 URL 和用量：

{
  "id": "task_...",
  "model": "gpt-image-2.5-flare",
  "status": "completed",
  "created_at": 1789970508,
  "finished_at": 1789970538,
  "output": {
    "created": 1789970532,
    "data": [{"url": "https://static.seedrouter.ai/media/tasks/task_example/0.png"}],
    "usage": {
      "input_tokens": 29,
      "output_tokens": 196,
      "total_tokens": 225
    }
  }
}

本 API 采用异步任务交付方式。它不是同步 Images SDK 的替代品；不支持 stream 和 partial_images。

错误

在任务创建之前被拒绝的请求，会返回 HTTP 错误状态码和一个 error 对象。受理之后才失败的任务，在查询时返回 HTTP 200，并带有 status: "failed" 和一个 error 对象。

错误码、HTTP 状态码和重试建议请参见公共错误目录。所有模型 API 使用同一套错误信封结构。

{
  "id": "task_...",
  "status": "failed",
  "error": {
    "code": 60002,
    "message": "Generation could not be completed. Please try again."
  }
}

如果提交本身超时，请先检查你的任务历史再重新提交：第一次请求有可能已经被受理。

实用建议

• 在提示词中描述材质、构图和光线。
• 做编辑时，既要说明要改什么，也要说明哪些应保持不变。
• 只需改动选定区域时，请使用遮罩。
• 需要长期保存时，请把返回的图像保存到你自己的存储中。

相关内容

• GPT Image 2.5 Playground 与定价
• 下载 OpenAPI
• 可复制的 Markdown