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-flare | Flare | 每张图固定价 |
gpt-image-2.5-sunburst | Sunburst | 每张图固定价 |
gpt-image-2.5-flare-official | Flare | 按 token 用量 |
gpt-image-2.5-sunburst-official | Sunburst | 按 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 | 怎么处理 |
|---|---|---|
20001 | 400 | 修正错误信息指出的字段 |
20002 | 400 | 原样使用四个模型 ID 之一 |
10001 | 401 | 检查 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 里不写代码试一次请求。



