GPT Image 2 API Python 调用教程:完整示例代码
完整的 GPT Image 2 API Python 示例:提交请求、轮询任务、把图片下载到本地、用参考图编辑,并稳妥地处理错误。
以 Markdown 阅读要在 Python 中调用 GPT Image 2 API,用 requests 库把请求 POST 到 https://api.seedrouter.ai/v1/images/generations,保存返回的任务 id,轮询 /v1/tasks/{id} 直到任务变为 completed,再下载它列出的图像 URL。下面的脚本用大约 40 行代码完成这四步,并把图片保存到本地。
设置好 SEEDROUTER_API_KEY 后即可直接运行。如果你还没有 Key,请先获取一个。
完整的 GPT Image 2 Python 脚本是什么样的?
import os
import time
import requests
API = "https://api.seedrouter.ai/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"}
def submit(body):
response = requests.post(f"{API}/images/generations", headers=HEADERS, json=body, timeout=60)
if response.status_code >= 400:
error = response.json()["error"]
raise RuntimeError(f"{response.status_code} {error['code']}: {error['message']}")
return response.json()["id"]
def wait(task_id, limit_seconds=600):
deadline = time.monotonic() + limit_seconds
while time.monotonic() < deadline:
task = requests.get(f"{API}/tasks/{task_id}", headers=HEADERS, timeout=30).json()
if task["status"] == "completed":
return [image["url"] for image in task["output"]["data"]]
if task["status"] == "failed":
raise RuntimeError(f"{task['error']['code']}: {task['error']['message']}")
time.sleep(3)
raise TimeoutError(f"Still running. Resume polling task {task_id}.")
def download(urls, prefix):
paths = []
for index, url in enumerate(urls):
path = f"{prefix}-{index}.png"
with open(path, "wb") as file:
file.write(requests.get(url, timeout=60).content)
paths.append(path)
return paths
task_id = submit({
"model": "gpt-image-2",
"prompt": "A matte ceramic vase on a sunlit table, soft shadows",
"size": "1024x1024",
"quality": "low",
"n": 2,
})
print("task", task_id)
print(download(wait(task_id), "vase"))用 python example.py 运行。它会先打印任务 ID,再打印两个 PNG 文件的路径:vase-0.png 和 vase-1.png。
每个函数分别做什么?
submit 发送请求并返回任务 ID。错误响应总会带一个 error 对象,包含数字 code 和 message,因此抛出的异常会告诉你该修改什么。例如,错误码为 20001、message 为 “Check the size parameter against the API documentation.” 的 400,表示尺寸违反了参数指南中的某条规则。
wait 每三秒轮询一次,直到任务结束。你这边设置的截止时间只会停止循环,不会停止任务:出图仍在继续,你之后可以用同一个 ID 继续轮询。以 failed 结束的任务会带着错误码抛出异常,并且不收费。
download 获取任务返回的每个 URL 并写入磁盘。结果 URL 只是交付的交接点,不是永久存储,所以想保留的图片要自己保存。示例中下载图片和调用 API 都用 requests;整个脚本请坚持使用同一个 HTTP 客户端,不要再混用标准库的 urllib。
如何修改图像设置?
所有设置都在请求体里。大多数人最先修改的字段:
| 字段 | 示例 | 作用 |
|---|---|---|
size | "1536x1024" | 输出尺寸;auto 由模型决定 |
quality | "medium" | low、medium、high 或 auto |
n | 4 | 图像数量,1 到 10 |
output_format | "jpeg" | png 或 jpeg |
background | "transparent" | 需要 png |
如果修改了 output_format,请把 download 中的 .png 扩展名改成对应的格式。完整的字段与限制见 GPT Image 2 API 文档。
如何在 Python 中编辑图像?
在同一个调用里以 URL 形式传入参考图。没有单独的编辑端点;加上 images 就会把请求变成编辑,mask 则把修改限制在某一块区域:
task_id = submit({
"model": "gpt-image-2",
"prompt": "Make the vase deep blue. Keep the table and the light unchanged.",
"images": [{"image_url": "https://example.com/vase.png"}],
})URL 必须是指向 PNG、JPEG 或 WebP 文件的公开 HTTPS 链接,最多可以发送 16 个。本地文件和 base64 字符串会被拒绝,所以请先把图片上传到你自己的存储,再传入它的 URL。
提交超时后脚本应该怎么做?
不要马上重新提交。POST 超时并不能证明请求被拒绝了;任务可能已经在运行并且已经扣费。先查看你最近的任务,或者在确认没有创建任务之后再重试请求。任务指南说明了如何区分这两种情况。
轮询则不同:轮询时超时没有任何害处。用同一个 ID 再次调用 wait 即可。
常见问题
可以改用 OpenAI 的 Python SDK 吗?
不能直接使用。这个 API 通过任务 ID 异步交付结果,而 SDK 的图像调用期望在响应中直接拿到成图。像上面那样用几行 requests 就能覆盖整个流程。
如何运行多个提示词?
逐个提交提示词,保存所有任务 ID,然后轮询它们。批量生成指南给出了一个重启后也能继续、不会重复付费的版本。
gpt-image-2-official 需要不同的代码吗?
不需要。只改 model 字符串,其他都不用动。两个 ID 接受相同的字段、返回相同的任务响应,只有计费方式不同。
保存好任务 ID,剩下的都是管道工作
提交、保存 ID、带截止时间轮询、下载返回的结果。这个模式就是整个集成。在写脚本之前,可以先在 GPT Image 2 Playground 里无需代码试一下提示词。



