GPT Image 2

GPT Image 2는 텍스트 프롬프트와 선택적인 참조 이미지를 입력으로 받습니다. 한 번 제출한 뒤 반환된 작업 ID를 보관하고, 그 작업을 조회해 완성된 이미지를 받아오세요. 두 개의 채널로 제공되며 채널마다 모델 ID가 따로 있지만, 파라미터는 같습니다.

모델 ID

두 ID 모두 같은 파라미터를 받고 모든 모드를 지원하며, 다른 점은 과금뿐입니다. 현재 가격은 모델 페이지에서 확인하세요. 아래 예시는 gpt-image-2를 사용합니다. 토큰 기준으로 과금하려면 gpt-image-2-official로 바꾸세요.

간단한 예제

curl https://api.seedrouter.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "An amber glass bottle on a cream background, studio lighting",
    "size": "1024x1024",
    "quality": "low"
  }'

엔드포인트

POST https://api.seedrouter.ai/v1/images/generations

생성, 참조 이미지 편집, 마스크 편집은 모두 같은 엔드포인트에서 처리됩니다. 응답에 담기는 것은 작업 ID이며 완성된 이미지가 아닙니다. API 키는 서버 측 코드에 보관하세요.

파라미터

크기 규칙

자주 쓰이는 값은 1024x1024, 1536x1024, 1024x1536입니다. 사용자 지정 크기는 다음 조건을 모두 만족해야 합니다:

• 가로와 세로가 16의 배수일 것.
• 어느 변도 3840픽셀을 넘지 않을 것.
• 가로세로 비율이 1:3에서 3:1 사이일 것.
• 전체 면적이 655,360에서 8,294,400픽셀 사이(양 끝 포함)일 것.

auto는 출력 크기를 모델에 맡깁니다. 16:9 같은 비율을 size로 보내지 마세요.

Playground에는 Auto, 비율, 사용자 지정 컨트롤이 있습니다. 비율 모드는 가로세로 비율과 1K·2K·4K 픽셀 예산 프리셋을 조합한 뒤, 계산된 size만 전송합니다. 이들은 UI 프리셋일 뿐 별도의 API 파라미터가 아닙니다. resolution이나 aspect_ratio를 보내지 마세요. 예를 들어 16:9 + 4K는 size: "3840x2160", 9:16 + 4K는 "2160x3840", 1:1 + 2K는 "2048x2048"을 전송합니다. 반올림과 변 길이 상한 때문에 선택한 등급보다 실제 픽셀 수가 줄어들 수 있습니다. 정확한 크기는 제출 전에 표시됩니다.

OpenAI는 2560×1440을 넘는 해상도를 실험적인 것으로 설명합니다. 위 제한 범위 안에서는 허용되지만, 해상도가 높다고 해서 디테일이 더 좋아진다는 보장은 없습니다.

품질 등급

초안에는 low를 사용하고, 결과를 비교한 뒤 더 높은 등급을 선택하세요. auto는 모델이 선택하도록 맡기는 것이며, 특정 등급이나 비용을 보장하지 않습니다.

투명 배경

GPT Image 2의 투명 배경은 프리뷰 단계입니다. 투명 배경을 원하면 background: "transparent"를 설정하고 PNG를 사용하세요. JPEG는 투명을 지원하지 않습니다. 압축은 JPEG에만 적용됩니다.

user는 API 연동용으로 제공되지만 Playground에서는 표시되지도, 자동으로 채워지지도 않습니다.

선택적 스칼라 설정(n, size, quality, background, output_format, output_compression, moderation)은 생략을 뜻하는 null을 허용합니다. 알 수 없는 필드는 거부됩니다. GPT Image 2에서는 input_fidelity를 설정할 수 없으며, 참조 입력은 항상 높은 충실도로 처리됩니다. style과 response_format은 다른 이미지 모델의 파라미터이므로 여기서는 받지 않습니다.

모드

모드를 지정하는 파라미터도, 따로 선택해야 하는 편집 엔드포인트도 없습니다.

참조 이미지 편집하기

curl https://api.seedrouter.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "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"},
    "output_format": "jpeg",
    "output_compression": 90
  }'

예제의 두 URL은 접근 가능한 본인의 이미지로 바꾸세요. 편집 영역을 지정하지 않는 참조 이미지 편집에서는 mask를 생략합니다.

미디어 입력

이 API는 URL 참조만 받습니다. OpenAI Files ID, base64 data URL, multipart 업로드는 받지 않습니다. Playground는 선택한 파일을 스토리지에 업로드한 뒤 그 URL을 전송합니다.

참조 이미지는 각 50MB 미만의 PNG, JPEG, WebP 파일을 가리키는 공개 HTTP(S) URL이어야 합니다. 마스크는 4MB 미만의 PNG여야 하며 첫 번째 참조 이미지와 크기가 같아야 합니다. 마스크의 투명 영역이 편집 대상을 표시합니다. 마스크는 모델에 대한 안내일 뿐 픽셀 단위로 정확한 경계를 보장하지 않습니다. 참조 이미지가 여러 장이면 마스크는 첫 번째 이미지에 적용됩니다. URL 미디어는 처리 중에 검증되므로, 유효하지 않거나 접근할 수 없는 미디어는 작업 실패로 이어질 수 있습니다.

Playground는 선택한 파일을 업로드하고 그 URL을 전송합니다. API 요청은 JSON URL 객체를 사용합니다. 파일 바이트, base64, data: URL, blob: URL, multipart 폼 데이터를 보내지 마세요.

과금에 영향을 주는 요소

현재 요금은 모델 가격 섹션에서 확인하세요. gpt-image-2(Standard)는 품질, 크기, 프롬프트와 상관없이 전달된 이미지 1장마다 고정 가격입니다. gpt-image-2-official(Official)의 최종 비용은 입력과 출력 사용량에 따라 정해지며, 품질, 출력 크기, 참조 이미지, 프롬프트 길이, 이미지 수가 모두 영향을 줍니다.

Playground의 추정치는 실측 샘플과 현재 요금을 기준으로 하며 확정 견적이 아닙니다. 최종 과금액은 계정의 사용 내역에서 확인하세요. 실패한 작업은 과금되지 않습니다.

출력 스키마

제출하면 작업 참조가 반환됩니다:

{
  "id": "task_...",
  "model": "gpt-image-2",
  "status": "processing",
  "created_at": 1789970508
}

작업 폴링

curl https://api.seedrouter.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY"

status가 completed 또는 failed가 될 때까지 3초 간격 정도로 절제된 주기로 폴링하세요. 폴링 중 네트워크 타임아웃이 발생해도 생성이 실패한 것은 아닙니다. 작업 ID를 유지한 채 조회를 이어가세요. 진행 상황 확인을 위해 다른 작업을 만들지 마세요.

전체 폴링 예제

위의 Python 제출 예제 다음에 실행하세요. 반환된 task_id를 사용하며 최대 10분간 대기합니다. 이 로컬 기한에 도달해도 폴링만 멈출 뿐이니, 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과 사용량을 반환합니다:

{
  "id": "task_...",
  "model": "gpt-image-2",
  "status": "completed",
  "created_at": 1789970508,
  "finished_at": 1789970538,
  "output": {
    "created": 1789970532,
    "data": [{"url": "https://static.seedrouter.ai/media/tasks/task_example/0.png"}],
    "usage": {
      "input_tokens": 29,
      "output_tokens": 196,
      "total_tokens": 225
    }
  }
}

이 API는 비동기 작업 전달 방식을 사용합니다. 동기식 Images SDK의 대체재가 아니며 stream과 partial_images는 지원하지 않습니다.

오류

작업이 생성되기 전에 거부된 요청은 HTTP 오류와 error 객체를 반환합니다. 접수된 뒤 실패한 작업은 조회 시 HTTP 200과 함께 status: "failed" 및 error 객체를 반환합니다.

코드, HTTP 상태, 재시도 지침은 공통 오류 카탈로그를 참고하세요. 모든 모델 API는 동일한 오류 구조를 사용합니다.

{
  "id": "task_...",
  "status": "failed",
  "error": {
    "code": 60002,
    "message": "Generation could not be completed. Please try again."
  }
}

제출 자체가 타임아웃된 경우에는 다시 보내기 전에 작업 내역을 확인하세요. 첫 번째 요청이 이미 접수되었을 수 있습니다.

팁

• 프롬프트에 재질, 구도, 조명을 구체적으로 설명하세요.
• 편집할 때는 무엇을 바꿀지와 무엇을 그대로 둘지를 함께 지정하세요.
• 선택한 영역만 바꾸고 싶다면 마스크를 사용하세요.
• 오래 보관해야 한다면 반환된 이미지를 직접 스토리지에 저장하세요.

관련 자료

• GPT Image 2 Playground와 가격
• OpenAPI 다운로드
• 복사 가능한 Markdown