GPT Image 2.5 API 파이썬 사용법: 동작하는 예제

GPT Image 2.5 API를 호출하려면 gpt-image-2.5-flare 같은 모델 ID와 프롬프트를 담아 https://api.seedrouter.ai/v1/images/generations로 POST를 보내고, 응답의 작업 id를 보관한 뒤, 상태가 completed가 될 때까지 GET /v1/tasks/{id}를 폴링하세요. 완료된 작업에는 이미지 URL이 들어 있습니다. 같은 엔드포인트로 텍스트-이미지 생성, 참조 이미지 편집, 마스크 편집을 모두 처리합니다.

이 가이드는 Python으로 처음부터 끝까지 실행할 수 있는 전체 과정을 JavaScript 코드와 함께 보여 주고, 가장 자주 마주치는 오류와 각 오류의 의미를 설명합니다.

첫 요청 전에 무엇이 필요한가요?

API 키와 모델 ID, 이 두 가지입니다.

API 키 페이지에서 키를 만들고 서버의 환경 변수에 보관하세요. 브라우저 코드에는 절대 넣지 마세요.

export SEEDROUTER_API_KEY="your-key"

그다음 GPT Image 2.5 모델 ID 네 개 중 하나를 고르세요. 정확히 그대로 복사하세요. 티어가 붙지 않은 gpt-image-2.5 ID는 없습니다.

어떤 모델로 시작할지 모르겠다면 Flare를 쓰세요. Sunburst가 언제 그만한 가치가 있는지는 Flare vs 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부터 저장하세요. 방금 비용을 낸 작업을 가리키는 유일한 핸들이며, 이미지가 렌더링되는 동안 프로세스가 재시작되더라도 이것으로 복구할 수 있습니다.

이미지는 어떻게 받나요?

작업이 끝날 때까지 몇 초 간격으로 폴링하세요. 이 루프는 최대 10분까지 기다립니다. 기한에 도달하면 멈추는 것은 루프일 뿐, 작업이 아닙니다.

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 클라이언트만 바뀝니다. 키가 브라우저에 닿지 않도록 서버에서 실행하세요.

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이어야 합니다. 참조 이미지는 각각 50 MB 미만의 PNG, JPEG, WebP로 최대 16장까지 보낼 수 있습니다. 마스크는 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 200을 반환하며, status: "failed"와 함께 코드 60001(콘텐츠 정책)이나 60002(생성 실패) 같은 error 객체가 담깁니다. 실패한 작업은 과금되지 않습니다. 오류 목록에는 잔액과 요청 한도 오류를 포함한 모든 코드와 각각의 다음 조치가 정리되어 있습니다.

자주 묻는 질문

이미지를 바로 반환하는 공식 Python SDK 호출이 있나요?

이 API에는 없습니다. 전달은 비동기 방식이라 항상 제출하고, 작업 ID를 보관하고, 폴링해야 합니다. stream과 partial_images는 지원하지 않습니다.

이미지를 한 번에 여러 장 요청할 수 있나요?

네. n을 1부터 10까지 설정하세요. 완료된 작업에는 전달된 이미지마다 URL이 하나씩 나열되며, 과금은 전달된 이미지만큼입니다.

투명 PNG는 어떻게 받나요?

background를 transparent로, output_format을 png로 설정하세요. JPEG에는 알파 채널이 없으므로, 그 조합은 실행 전에 거부됩니다.

작업 ID를 중심으로 연동을 완성하세요

작업 ID를 받는 즉시 저장하고, 기한을 두고 폴링하며, 폴링 타임아웃은 "실패"가 아니라 "아직 실행 중"으로 취급하세요. 모든 필드와 제한을 포함한 나머지는 GPT Image 2.5 API 레퍼런스에 있으며, 코드 없이 요청을 시험해 보려면 Playground를 사용하세요.