GPT Image 2 API 파이썬 사용법: 완전한 예제

Python에서 GPT Image 2 API를 사용하려면 requests 라이브러리로 https://api.seedrouter.ai/v1/images/generations에 요청을 POST하고, 반환된 작업 id를 보관한 뒤, 작업이 completed가 될 때까지 /v1/tasks/{id}를 폴링하고, 작업에 담긴 이미지 URL을 내려받으면 됩니다. 아래 스크립트는 약 40줄로 네 단계를 모두 처리하고 이미지를 디스크에 저장합니다.

SEEDROUTER_API_KEY만 설정하면 그대로 실행됩니다. 아직 키가 없다면 먼저 키를 발급받으세요.

완전한 GPT Image 2 스크립트는 어떤 모습인가요?

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를 반환합니다. 오류 응답에는 항상 숫자 code와 message를 담은 error 객체가 있으므로, 예외 메시지만 보면 무엇을 고쳐야 하는지 알 수 있습니다. 예를 들어 코드 20001에 메시지가 “Check the size parameter against the API documentation.”인 400은 크기가 파라미터 가이드의 규칙 중 하나를 어겼다는 뜻입니다.

**wait**은 작업이 끝날 때까지 3초마다 폴링합니다. 내 쪽의 마감 시간은 작업이 아니라 루프를 멈출 뿐입니다. 렌더링은 계속 진행되며, 나중에 같은 ID로 폴링을 재개할 수 있습니다. failed로 끝난 작업은 오류 코드와 함께 예외를 발생시키며 과금되지 않습니다.

**download**는 작업이 반환한 모든 URL을 가져와 디스크에 씁니다. 결과 URL은 전달을 위한 인계 수단이지 영구 저장소가 아니므로, 보관할 이미지는 저장해 두세요. 이 예제는 API 호출뿐 아니라 다운로드에도 requests를 사용합니다. 표준 라이브러리의 urllib를 섞지 말고 HTTP 클라이언트 하나로 통일하세요.

이미지 설정은 어떻게 바꾸나요?

모든 설정은 요청 본문에 있습니다. 대부분의 사람이 가장 먼저 바꾸는 필드는 다음과 같습니다.

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에서 코드 없이 프롬프트를 시험해 보세요.