GPT Image 2 글로벌 미러와 프록시: 국제 팀을 위한 저지연 접근

대상 모델: gpt-image-2
추론 엔드포인트: https://api.toapis.com/v1/images/generations
관련 글: GPT Image 2 API 가이드 · GPT Image 2 요금 · GPT-Image-2.6 API 가이드

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

• 작업: 국제 팀의 클라이언트가 gpt-image-2를 호출할 때마다 벤더 오리진으로 장거리 세션을 새로 열지 않고, 하나의 ToAPIs 이미지 게이트웨이를 가리키게 합니다.
• 계약: POST /v1/images/generations에서 모델 ID gpt-image-2를 사용합니다. 현재 문서의 필드에는 prompt(최대 32,000자), 종횡비인 size(1:1 또는 16:9 등, 1024x1024 같은 픽셀 문자열이 아님), 그리고 티어인 resolution(1k, 2k, 4k)이 있습니다.
• 지역: 공식 ToAPIs 문서는 중국 본토 사용자에게 베이스 URL https://toapis.cn을 쓰라고 안내합니다. 이 시리즈의 국제 예시는 https://api.toapis.com을 사용합니다. 경로, 모델 ID, Bearer 헤더는 같고 오리진만 바뀝니다.
• 비동기 프로토콜: 이미지 생성은 작업 id를 반환합니다. completed 또는 failed가 될 때까지 GET /v1/images/generations/{task_id}(또는 GET /v1/tasks/{task_id})를 폴링하세요. 클라이언트의 벽시계 시간은 생성 시간과 다르며, 시간 초과가 작업 실패의 증거는 아닙니다.
• 이 글이 주장하지 않는 것: 검증되지 않은 POP 목록, 핸드셰이크 시간, 종단 지연 목표를 제시하지 않습니다. 그런 숫자는 자신의 경로에서 측정하세요. 파라미터와 SKU 비교는 API 가이드와 2.6 가이드에 있습니다.

2. ToAPIs 게이트웨이로 국제 팀의 경로를 맞추기

벤더 본거지에서 먼 팀이 느끼는 지연은 대개 두 가지입니다. 연결을 여는 시간과 모델이 실제로 렌더링하는 시간입니다. 이를 “API가 느리다”는 하나의 숫자로 합치면 최적화 대상을 잘못 고릅니다. 전자는 네트워크 문제이며, 문서화된 더 가까운 ToAPIs 오리진을 쓰고 준비된 HTTP 세션을 재사용해 다룰 수 있습니다. 후자는 생성 시간이며, 작업이 수락된 뒤에 관찰합니다.

ToAPIs는 통합 이미지 생성 경로를 제공합니다. 공식 문서가 현재 안내하는 주소는 https://toapis.com이며, 중국 본토 사용자에게는 https://toapis.cn으로 바꾸라고 합니다. 이 시리즈의 GPT Image 2 API 가이드를 포함한 글은 같은 경로를 https://api.toapis.com으로 보냅니다. 환경마다 베이스 URL을 하나만 고르고 설정으로 두며, 같은 서비스에서 오리진을 섞지 마세요.

그림 1: 클라이언트를 문서화된 하나의 ToAPIs 오리진에 두고 세션을 재사용하며, 이미지 생성을 장거리 동기 왕복이 아닌 비동기 작업으로 다룹니다.

공개되지 않은 지연 숫자에 기대지 않는 실무 습관입니다.

• 환경마다 오리진은 하나. 싱가포르와 프랑크푸르트 서비스는 같은 모델 ID와 페이로드를 공유할 수 있습니다. 각자 벤더 URL을 만들지 마세요.
• 연결을 재사용하세요. HTTP keep-alive(클라이언트가 HTTP/2를 지원하면 함께)를 켜서, 제출이나 폴링마다 TLS를 다시 하지 마세요.
• 제출과 대기를 분리하세요. 작업 id를 바로 저장합니다. 상한이 있는 간격으로 폴링하거나, 작업 웹훅을 우선하고 폴링은 보조로 두세요.
• “같은 프롬프트는 에지 캐시”를 비용 절감 수단으로 쓰지 마세요. 반복 프롬프트가 에지 캐시에서 무료로 나온다는 ToAPIs의 문서화된 보장은 없습니다. 계정 조건에 다른 규정이 없으면, 제출한 작업은 두 건으로 계획하세요.

요청 계약도 쉽게 낡습니다. 오래된 예시는 size를 1024x1024로 보내고 quality: "standard"를 붙이기도 합니다. 현재 gpt-image-2 API 레퍼런스와 ToAPIs 프론트엔드 계약에서 size는 종횡비(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)이고, resolution은 티어(1k, 2k, 4k)입니다. 현재 플레이그라운드 계약에서 정확한 gpt-image-2는 quality 필드를 노출하지 않으며, quality는 gpt-image-2-vip 같은 ID에 있습니다. 실제로 호출하는 ID를 확인하세요.

참조 이미지는 reference_images에 둡니다(공개 URL만, 최대 14장). image_urls는 하위 호환 별칭이며 reference_images로 정규화됩니다. base64는 보내지 말고 먼저 업로드하세요. 사용자 지정 비율, 추가 품질 옵션, 공식 SKU 동작은 API 가이드와 모델 가이드를 보세요.

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

1단계: cURL로 제출

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": "Minimalist product still of a matte ceramic pour-over kettle on slate, soft side light, no typography",
    "size": "1:1",
    "resolution": "1k",
    "n": 1,
    "response_format": "url"
  }'

2단계: Python 제출과 폴링

필드 이름과 응답 엔벨로프는 계정 API 레퍼런스에 맞추세요. 예시는 문서화된 이미지 상태 경로와 completed / failed를 사용합니다. 중국 본토 오리진이 필요한 환경에서만 BASE를 https://toapis.cn으로 바꾸세요.

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 = "1:1",
    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 = 180) -> 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__":
    task_id = dispatch_image(
        "Minimalist product still of a matte ceramic pour-over kettle on slate, soft side light, no typography"
    )
    print("Task:", task_id)
    print("Image:", poll_image_task(task_id))

베이스 URL, 모델 ID, size, resolution을 작업 기록 옆에 두세요. 나중에 클라이언트를 gpt-image-2에서 gpt-image-2-vip나 2.6 SKU로 옮길 때는 한 번에 변수 하나만 바꾸고 해당 가이드를 다시 읽으세요. 과금 단위가 자동으로 같지는 않습니다.

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

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

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

5. 요금과 FinOps ROI

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

• 기획 초안이나 이전 글의 단가를 그대로 쓰지 마세요. 카탈로그 요금, 해상도 배수, 실패 작업 처리는 SKU와 계정에 따라 달라집니다. 일부 GPT Image 2.x ID는 장당 과금입니다. 2.6 가이드는 해당 세대가 토큰 과금이라고 설명합니다. 실제로 호출하는 모델 ID의 요금을 확인하세요.
• 경로를 바꾼다고 모델 단가가 자동으로 바뀌지는 않습니다. api.toapis.com과 toapis.cn은 베이스 URL 선택일 뿐, 문서화된 할인이 아닙니다. FinOps 효과는 클라이언트 시간 초과 후 중복 제출을 피하고, 1k로 초안을 만들며, 알맞은 SKU를 고르는 데서 옵니다.
• 공식 벤더 계약에는 지역 청구 제약, 약정, 선결제 하한이 붙는 경우가 많습니다. ToAPIs 과금은 보통 사용량 기준입니다. 유효 조건은 계정에서 확인하세요.
• 더 깊은 요금 논의는 GPT Image 2 요금 글을 배경으로 삼되, 예측에 넣기 전에 라이브 카탈로그로 숫자를 하나하나 확인하세요.

6. 자주 묻는 질문

구조화 FAQ는 frontmatter를 보세요. 요약: ToAPIs 오리진을 바꿔도 모델 ID나 문서화된 요청 형태는 바뀌지 않습니다. 중국 본토 사용자는 공식 문서의 toapis.cn 안내를 따르세요. 이미지 작업은 비동기입니다. size는 종횡비, resolution은 티어입니다. 반복 프롬프트가 무료 에지 캐시로 나온다는 문서화된 보장은 없습니다.

7. 액션 체크리스트

• ToAPIs 개발자 포털에서 키를 만듭니다.
• 환경마다 베이스 URL을 하나 정하고(https://api.toapis.com, 필요하면 https://toapis.cn), gpt-image-2, size: "1:1", resolution: "1k"로 위의 cURL을 스모크 테스트합니다.
• 작업 id를 저장하고, GET /v1/images/generations/{id}를 기한 있게 폴링하며, 429에서는 Retry-After를 따릅니다.
• 다음: 파라미터는 GPT Image 2 API 가이드, SKU를 옮기면 2.6 가이드, 새 계정은 무료 크레딧 안내.