Claude Opus 5.5 已在 SeedRouter 上线

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
n4图像数量,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 里无需代码试一下提示词。

相关指南