Claude Opus 5.5 已在 SeedRouter 上线

GPT Image 2.5 API Python 调用:一个可运行的示例

用 Python 和 JavaScript 调用 GPT Image 2.5 API,轮询任务拿到图像 URL,用参考图编辑图像,并排查模型 ID 与参数错误。

以 Markdown 阅读

调用 GPT Image 2.5 API 的方法是:向 https://api.seedrouter.ai/v1/images/generations 发送 POST 请求,带上 gpt-image-2.5-flare 这样的模型 ID 和提示词,保存响应里的任务 id,然后轮询 GET /v1/tasks/{id},直到状态变为 completed。完成的任务里包含图像的 URL。文生图、参考图编辑和遮罩编辑都走同一个端点。

本教程给出一条完整、可运行的 Python 调用路径,并附上等效的 JavaScript 写法,最后列出最常遇到的错误及其含义。

发送第一个请求前需要准备什么?

两样东西:一个 API Key 和一个模型 ID。

在 API Key 页面创建 Key,并把它保存在服务端的环境变量中,绝不要放进浏览器端代码:

export SEEDROUTER_API_KEY="your-key"

然后从四个 GPT Image 2.5 模型 ID 中选一个。请原样复制;不存在不带档次的 gpt-image-2.5 这个 ID。

模型 ID模型计费方式
gpt-image-2.5-flareFlare每张图固定价
gpt-image-2.5-sunburstSunburst每张图固定价
gpt-image-2.5-flare-officialFlare按 token 用量
gpt-image-2.5-sunburst-officialSunburst按 token 用量

如果不确定从哪个模型开始,就用 Flare;Flare 与 Sunburst 对比解释了什么时候值得用 Sunburst。

如何用 Python 生成图像?

提交后会立即返回。响应是一个任务引用,而不是图像本身。

import os
import requests

response = requests.post(
    "https://api.seedrouter.ai/v1/images/generations",
    headers={"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"},
    json={
        "model": "gpt-image-2.5-flare",
        "prompt": "An amber glass bottle on a cream background, studio lighting",
        "size": "1024x1024",
        "quality": "low",
    },
    timeout=60,
)
response.raise_for_status()
task_id = response.json()["id"]

在做任何其他事情之前,先保存 task_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 下载下来,自行存储。结果 URL 只是交付的交接方式,不是长期存储。

同样的调用用 JavaScript 怎么写?

请求完全相同,只是换了 HTTP 客户端。请在服务端运行,这样 Key 永远不会到达浏览器。

const response = await fetch('https://api.seedrouter.ai/v1/images/generations', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SEEDROUTER_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-image-2.5-flare',
    prompt: 'An amber glass bottle on a cream background, studio lighting',
    size: '1024x1024',
    quality: 'low',
  }),
});
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const { id: taskId } = await response.json();

用同样的请求头轮询 GET https://api.seedrouter.ai/v1/tasks/${taskId},做法与 Python 循环完全一致。

如何编辑已有图像?

在同一个请求里加上参考图即可。没有单独的编辑端点,也没有模式字段:发送 images 就会变成编辑,再加上 mask 就能把修改限制在某一块区域。

{
  "model": "gpt-image-2.5-sunburst",
  "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"}
}

输入必须是公开的 HTTPS URL。最多可以发送 16 张参考图,格式为 PNG、JPEG 或 WebP,每张小于 50 MB。遮罩是小于 4 MB 的 PNG,尺寸与第一张参考图相同,其透明区域标出要修改的部分。Base64 字符串、data: URL 和文件上传都会被拒绝,所以请先把文件上传到你自己的存储,再发送 URL。

为什么 API 提示模型不可用?

HTTP 400 加错误码 20002(“The requested model is not available.”)表示 model 的值不是 API 提供的 ID。常见原因是差了一点点:写成了不带档次的 gpt-image-2.5、把点写成横杠的 gpt-image-2-5-flare,或者 sunburst 拼错。请从上面的表格里复制 ID。

参数错误会在检查模型之前报告。如果请求里还有无效字段,你会收到 20001,错误信息会指出是哪个字段,例如 quality。先修好它;如果 ID 仍然不对,下一次尝试时就会出现模型错误。

错误码HTTP怎么处理
20001400修正错误信息指出的字段
20002400原样使用四个模型 ID 之一
10001401检查 Authorization 请求头

任务在被受理之后也可能失败。这时查询仍然返回 HTTP 200,但带有 status: "failed" 和一个 error 对象,比如错误码 60001(内容策略)或 60002(生成失败)。失败的任务不收费。错误码目录列出了每个错误码,包括余额和限流错误,以及每种情况下一步该怎么做。

常见问题

有没有官方 Python SDK 调用能直接返回图像?

在这个 API 上没有。交付是异步的:你总是先提交、保存任务 ID,再轮询。不支持 stream 和 partial_images。

可以一次请求多张图吗?

可以。把 n 设为 1 到 10。完成的任务会为每张交付的图像列出一个 URL,按实际交付的图像张数计费。

如何得到透明背景的 PNG?

把 background 设为 transparent,output_format 设为 png。JPEG 没有 alpha 通道,所以这种组合会在运行前就被拒绝。

围绕任务 ID 完成接入

收到任务 ID 的那一刻就存下来,带着期限去轮询,把轮询超时当作「仍在运行」而不是「已失败」。其余所有内容,包括每个字段和限制,都在 GPT Image 2.5 API 文档里;你也可以在 Playground 里不写代码试一次请求。

相关指南