tutorial8 분 읽기

GPT Image 2로 네이티브 4K 이미지 생성하기: 종횡비와 업스케일 워크플로

현재 GPT Image 2 계약으로 네이티브 4K 를 생성합니다. size 에는 종횡비를, resolution 에는 4k 를 지정하세요. 문서화된 upscale: true 플래그는 없으며, 4K 픽셀 크기는 선택한 비율에 따라 달라집니다.

ToAPIs Engineering & Evaluation Team
TL;DR - 핵심 요약
  • 정확한 gpt-image-2 는 resolution 을 1k, 2k, 4k 의 일급 티어로 노출합니다. 네이티브 4K 는 POST /v1/images/generations 에서 resolution: "4k" 를 보내는 것이며, 서버 측 upscale: true 플래그나 1024x1024 같은 size 문자열이 아닙니다.
  • size 는 종횡비(1:1, 16:9 및 기타 문서화된 비율)입니다. API 레퍼런스는 픽셀 표를 공개하며, 16:9 의 4k 는 3840x2160, 1:1 의 4k 는 2880x2880 입니다.
  • 현재 플레이그라운드는 resolution 이 4K 일 때 5:4 와 4:5 를 생략하지만, API 크기 표에는 두 비율의 4k 픽셀 값이 있습니다. 이 비율이 필요하면 실시간 레퍼런스로 확인하세요.
  • 작업은 비동기입니다. 작업 id 를 저장하고 GET /v1/images/generations/{id} 를 폴링하세요. 클라이언트 타임아웃은, 특히 4k 에서, 실패의 증거가 아닙니다.
  • 오래된 1024px / 2048px 단가로 예산을 짜지 마세요. 계정에서 해당 모델 ID 의 실시간 티어별 요율을 확인하세요.

GPT Image 2로 네이티브 4K 이미지 생성하기: 종횡비와 업스케일 워크플로

대상 모델: gpt-image-2
추론 엔드포인트: https://api.toapis.com/v1/images/generations
관련 문서: GPT Image 2 API 가이드 · 인페인팅과 아웃페인팅 · 글로벌 미러와 프록시 · API 크기 레퍼런스


1. 핵심 요약 및 개요 (TL;DR)

  • 목표: 실제로 필요한 종횡비로, 문서화된 4K 티어 이미지를 한 번의 gpt-image-2 요청에서 얻는 것입니다.
  • 계약: 모델 ID gpt-image-2 로 POST /v1/images/generations 를 호출합니다. size 는 종횡비(1:1, 16:9 및 기타 문서화된 비율)이고, resolution 은 1k, 2k, 또는 4k 입니다. 공식 레퍼런스는 각 쌍의 픽셀 크기를 공개합니다.
  • 보내면 안 되는 것: size: "2048x2048", 정확한 gpt-image-2 의 quality: "hd", 2048 px 렌더를 3840x2160 으로 바꾼다고 주장하는 지어낸 upscale: true 필드. 4K 는 일급 resolution 값입니다.
  • 비동기 프로토콜: 제출 호출은 작업 id 를 반환합니다. completed 또는 failed 가 될 때까지 GET /v1/images/generations/{id}(또는 GET /v1/tasks/{id})를 폴링하세요. 4K 작업은 1K 초안보다 오래 걸릴 수 있습니다. 클라이언트 타임아웃은 실패의 증거가 아닙니다.
  • FinOps: 1k 로 초안을 만들고, 채택한 프롬프트를 4k 로 올린 뒤, 실시간 티어별 요율을 확인하세요. 오래된 1024 px / 2048 px 가격 행을 예측에 복사하지 마세요.

2. 종횡비, 해상도 티어, 네이티브 4K 출력

현재 gpt-image-2 계약은 형태와 티어를 나눕니다. size 는 종횡비를, resolution 은 품질 티어를 고르고, 서비스가 둘에서 픽셀 너비와 높이를 도출합니다. 그래서 "4K 이미지"가 항상 3840x2160 인 것은 아닙니다. 그 크기는 size: "16:9" 와 resolution: "4k" 의 문서화된 결과입니다. 정사각 4K 출력은 2880x2880 으로 문서화되어 있습니다.

공식 레퍼런스의 프리셋 비율은 다음과 같습니다.

1:1, 3:2, 2:3, 4:3, 3:4, 5:4, 4:5, 16:9, 9:16, 2:1, 1:2, 21:9, 9:21

auto 를 넘겨 업스트림에 맡길 수도 있지만, 최종 비율과 픽셀 크기는 보장되지 않습니다. 정확한 gpt-image-2 에는 custom 픽셀 크기 필드가 문서화되어 있지 않습니다. 사용자 정의 width:height 비율(예: 7:4)은 gpt-image-2-vip 와 gpt-image-2-official 에 문서화되어 있으며, 각 제한(변은 16의 배수, 긴 변은 최대 3,840 px, 비율은 최대 3:1, 총 픽셀은 655,360에서 8,294,400)을 따릅니다.

정확한 gpt-image-2 의 공식 크기 표는 다음과 같습니다.

size1k2k4k
1:11024x10242048x20482880x2880
3:21536x10242048x13603520x2336
2:31024x15361360x20482336x3520
4:31024x7682048x15363312x2480
3:4768x10241536x20482480x3312
5:41280x10242560x20483216x2576
4:51024x12802048x25602576x3216
16:91536x8642048x11523840x2160
9:16864x15361152x20482160x3840
2:12048x10242688x13443840x1920
1:21024x20481344x26881920x3840
21:92016x8642688x11523840x1648
9:21864x20161152x26881648x3840

이 표 옆에는 두 가지 주의가 필요합니다.

  • 현재 ToAPIs 플레이그라운드는 4K 에서도 3:2 와 2:3 을 유지하지만 5:4 와 4:5 는 제외합니다. 위 표에는 두 비율의 4k 픽셀 값이 있습니다. 제품에서 4k 의 5:4 또는 4:5 가 필요하면 실시간 요청으로 확인하고, 플레이그라운드 제한을 API 한도로 단정하지 마세요.
  • 화면마다 소문자(4k)와 대문자(4K)가 섞여 있습니다. 공식 gpt-image-2 예시는 소문자를 쓰고, 플레이그라운드 설정은 1K / 2K / 4K 를 씁니다. 클라이언트에서는 API 레퍼런스를 따르고, 대소문자를 두 번째 매개변수로 취급하지 마세요.

거친 2×2 노드 격자가 육각형 게이트웨이를 지나 더 고운 고해상도 격자로 흐르는 모습

그림 1: 해상도는 일급 요청 필드입니다. 문서화된 경로는 4k 를 직접 요청하는 것이며, 후처리 업스케일러 플래그를 만들어 내는 것이 아닙니다.

ToAPIs 에는 네이티브 2048 px 렌더를 3840x2160 으로 바꾸는 문서화된 upscale: true 스위치가 없습니다. 이미 1K 또는 2K 이미지가 있고 더 큰 결과가 필요하다면, 지원되는 방법은 새 생성(선택적으로 초안을 reference_images 에 넣고)을 resolution: "4k" 로 보내는 것입니다. 자체 자산에서 측정하지 않았다면 글자 선명도, "300 DPI 인쇄 마스터", 아티팩트 없는 업스케일을 약속하지 마세요.

정확한 gpt-image-2 는 선택적 background: "transparent" 와 최대 14개의 reference_images URL 도 받습니다. 현재 플레이그라운드 계약에서는 quality 를 노출하지 않습니다. quality 는 gpt-image-2-vip 같은 ID 의 필드입니다.


3. 프로덕션 구현: cURL과 Python

이 시리즈의 국제 예시는 https://api.toapis.com 을 사용합니다. 공식 문서는 중국 본토 사용자에게 https://toapis.cn 을 쓰라고 안내합니다. 환경마다 오리진은 하나만 유지하세요.

1단계: cURL로 네이티브 4K 제출

bash
curl -X POST "https://api.toapis.com/v1/images/generations" \
  -H "Authorization: Bearer $TOAPIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Wide architectural photograph of a concrete pavilion at dusk, still water in the foreground, no typography, no logos",
    "size": "16:9",
    "resolution": "4k",
    "n": 1,
    "response_format": "url"
  }'

이 요청은 문서상 3840x2160 을 목표로 합니다. 정사각 4K 마스터가 필요하면 size 를 1:1 로 바꾸세요(문서화된 크기는 2880x2880). 9:16 스토리 프레임이면 size: "9:16"(문서화된 크기는 2160x3840)을 쓰세요.

2단계: Python으로 초안을 만든 뒤 승격

1k 에서 반복하고, 채택한 프롬프트(및 선택적 참고 URL)를 저장한 뒤 4k 로 다시 제출하세요. 폴링 헬퍼는 미러와 프록시 가이드 와 같은 비동기 계약입니다.

python
import os
import time
import requests

API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
ENDPOINT = f"{BASE}/v1/images/generations"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}


def dispatch_image(
    prompt: str,
    size: str = "16:9",
    resolution: str = "1k",
    model: str = "gpt-image-2",
    reference_images: list[str] | None = None,
) -> str:
    payload = {
        "model": model,
        "prompt": prompt,
        "size": size,
        "resolution": resolution,
        "n": 1,
        "response_format": "url",
    }
    if reference_images:
        payload["reference_images"] = reference_images
    res = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=30)
    res.raise_for_status()
    data = res.json()
    task_id = data.get("id") or data.get("task_id")
    if not task_id:
        raise RuntimeError(f"Unexpected submission envelope: {data}")
    return task_id


def poll_image_task(task_id: str, deadline_s: int = 300) -> str:
    poll_url = f"{BASE}/v1/images/generations/{task_id}"
    interval = 2.0
    start = time.time()
    while time.time() - start < deadline_s:
        time.sleep(interval)
        poll = requests.get(poll_url, headers=HEADERS, timeout=15)
        if poll.status_code == 429:
            retry_after = poll.headers.get("Retry-After")
            time.sleep(float(retry_after) if retry_after else min(interval * 2, 20))
            continue
        poll.raise_for_status()
        data = poll.json()
        status = data.get("status")
        if status == "completed":
            return data["result"]["data"][0]["url"]
        if status == "failed":
            raise RuntimeError(f"Generation failed: {data.get('error')}")
        interval = min(interval * 1.5, 8.0)
    raise TimeoutError(
        f"Task {task_id} exceeded {deadline_s}s; check status before retrying"
    )


if __name__ == "__main__":
    prompt = (
        "Wide architectural photograph of a concrete pavilion at dusk, "
        "still water in the foreground, no typography, no logos"
    )
    draft_id = dispatch_image(prompt, size="16:9", resolution="1k")
    print("Draft:", draft_id, poll_image_task(draft_id))
    final_id = dispatch_image(prompt, size="16:9", resolution="4k")
    print("4K:", final_id, poll_image_task(final_id, deadline_s=300))

4K 폴링 시한은 1K 초안보다 길게 잡으세요. 작업 id 는 즉시 저장해 클라이언트 타임아웃 이후에도 상태 조회로 해결할 수 있게 하세요. 나중에 클라이언트를 gpt-image-2-vip(사용자 정의 비율, quality) 또는 gpt-image-2-official 로 바꿀 때는 변수를 하나씩만 바꾸고 해당 ID 의 레퍼런스를 다시 읽으세요. 과금 단위는 자동으로 같지 않습니다.


4. 오류 처리 및 상태 매트릭스

아래 분류는 진단의 출발점일 뿐이며 ToAPIs 의 정확한 오류 코드를 보장하지 않습니다. HTTP 제출이 성공해도 작업 status 를 읽어야 합니다.

HTTP 상태흔한 분류권장 조치
400잘못된 필드 또는 지원되지 않는 조합size 가 문서화된 비율인지, resolution 이 1k / 2k / 4k 인지 확인하고, 2048x2048 같은 픽셀 문자열이나 문서화되지 않은 upscale 플래그를 보내지 않았는지 확인하세요
401API 키 누락 또는 무효ToAPIs 대시보드에서 키를 교체하고 Authorization 헤더를 확인하세요
429속도 또는 동시성 제한Retry-After 가 있으면 따르고, 지터를 넣어 백오프하며, 안전할 때만 재시도하세요
5xx 또는 네트워크 타임아웃게이트웨이 또는 업스트림의 일시적 문제다시 제출하기 전에 작업 상태를 확인하세요. 4K 작업은 클라이언트 타임아웃 이후에도 in_progress 일 수 있습니다

WaitTime=min⁡(MaxWait,BaseInterval×2attempt)+Uniform(0,1)\text{WaitTime} = \min(\text{MaxWait}, \text{BaseInterval} \times 2^{\text{attempt}}) + \text{Uniform}(0, 1)


5. 요금과 FinOps ROI

Estimated cost=successful billable images×current account rate for that model, size, and resolution\text{Estimated cost} = \text{successful billable images} \times \text{current account rate for that model, size, and resolution}

  • 오래된 단가를 재사용하지 마세요. 예를 들어 1024 px 의 $0.024 또는 2048 px 의 $0.072. 이 행은 이미 낡은 크기 계약에 속합니다.
  • GPT Image 2 모델 가이드 는 현재 표준 gpt-image-2 의 ToAPIs 랜딩 비교가로 1K / 2K / 4K 에서 장당 $0.015 / $0.020 / $0.025 를 보여 줍니다. 게시된 비교가로만 보고, 계정과 실제로 호출하는 모델 ID 에 적용되는 요율을 확인하세요.
  • 비용을 줄이는 루프는 1k 로 초안을 만든 뒤 채택한 프롬프트(와 참고 이미지)를 4k 로 올리는 것입니다. 성공한 작업이 두 번이면, 계정 약관에 달리 적혀 있지 않는 한 두 장의 과금입니다. 같은 프롬프트를 무료로 확대한다는 문서화된 지름길은 없습니다.
  • 공식 벤더의 토큰 가격과 ToAPIs 의 요청 단위 가격은 서로 바꿔 쓸 수 없습니다. gpt-image-2-vip 나 공식 채널 SKU 로 옮긴다면 해당 ID 의 요금표를 다시 읽으세요.
  • 배경은 GPT Image 2 요금 글 을 본 뒤, 예측에 넣기 전에 실시간 카탈로그로 모든 숫자를 검증하세요.

6. 자주 묻는 질문

자세한 내용은 frontmatter 의 FAQ 를 보세요. 요약: 4K 는 일급 resolution 값이지 upscale 플래그가 아닙니다. 픽셀 크기는 size 와 resolution 모두에 달려 있습니다. size 에 1024x1024 를 보내지 마세요. 4k 에서 5:4 / 4:5 가 필요하면 실시간 API 로 확인하세요. 게시된 1K / 2K / 4K 요율은 계정에서 확인해야 합니다.


7. 액션 체크리스트

  • ToAPIs 개발자 포털 에서 키를 만드세요.
  • 환경마다 베이스 URL 을 하나 정하고(https://api.toapis.com, 필요한 경우 https://toapis.cn), size: "16:9" 와 resolution: "1k" 로 cURL 조각을 스모크 테스트하세요.
  • 같은 프롬프트를 resolution: "4k" 로 올리고, 해당 비율의 문서화된 픽셀 크기를 확인하세요(16:9 는 3840x2160).
  • 작업 id 를 저장하고, 4K 폴링 시한을 더 길게 잡으며, 429 에서는 Retry-After 를 지키세요.
  • 다음 읽을거리: 기존 프레임을 편집한다면 인페인팅과 아웃페인팅 가이드, 더 넓은 매개변수 맵은 API 가이드.

본문에서 언급된 모델 및 API

OpenAIIMAGE

GPT-Image-2

현재 요율:3 credits /request
OpenAIIMAGE

GPT-Image-2 VIP

현재 요율:3.38 credits /request

관련 기술 블로그

tutorial8분 읽기

GPT Image 2 이미지 편집 API로 인페인팅과 아웃페인팅 마스터하기

현재 GPT Image 2 계약으로 기존 이미지를 편집합니다. gpt-image-2는 참고 이미지로 프롬프트 기반 수정을, gpt-image-2-official은 마스크로 정밀 인페인팅을 수행하며, 둘 다 비동기 generations 엔드포인트를 사용합니다.

TO
ToAPIs Engineering & Evaluation Team
#GPT Image 2