tutorial8 분 읽기

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

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

ToAPIs Engineering & Evaluation Team
TL;DR - 핵심 요약
  • 현재 ToAPIs 이미지 계약은 비동기 POST /v1/images/generations 이며, 동기 multipart /v1/images/edits 도, gpt-image-2-edit 라는 카탈로그 ID 도 아닙니다.
  • 정확한 gpt-image-2 는 reference_images(공개 URL만, 최대 14장)로 프롬프트 기반 편집을 지원합니다. 알파 마스크를 쓰는 픽셀 단위 인페인팅은 gpt-image-2-official 의 mask_url 과 image_urls 로 문서화되어 있습니다.
  • size 는 1:1 또는 16:9 같은 종횡비이고, resolution 은 1k, 2k, 4k 티어입니다. size 에 1024x1024 같은 픽셀 문자열을 보내지 마세요.
  • 문서화된 outpaint 플래그는 없습니다. 캔버스를 확장하려면 size 를 목표 비율로 바꾸고, 원본을 참고 이미지로 전달한 뒤, 프롬프트에 확장 방식을 적습니다.
  • 작업 id 를 저장하고 GET /v1/images/generations/{id} 를 폴링하세요. 클라이언트 타임아웃은 작업 실패의 증거가 아닙니다.

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

대상 모델: gpt-image-2, gpt-image-2-official
추론 엔드포인트: https://api.toapis.com/v1/images/generations
관련 문서: GPT Image 2 API 가이드 · 4K 종횡비 워크플로 · 글로벌 미러와 프록시 · 공식 인페인팅 레퍼런스


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

  • 목표: 기존 이미지의 일부 영역을 교체하거나(인페인팅) 캔버스를 새 종횡비로 확장하되(아웃페인팅), 문서화되지 않은 두 번째 API 를 만들지 않는 것입니다.
  • 계약: 카탈로그에 실제로 있는 모델 ID 만 사용하세요. 정확한 gpt-image-2 는 prompt, 비율인 size, 1k / 2k / 4k 인 resolution, 선택적 reference_images 를 받습니다. 마스크 기반 인페인팅은 gpt-image-2-official 에서 image_urls 와 mask_url 로 문서화되어 있습니다.
  • 현재 계약이 아닌 것: gpt-image-2-edit 라는 모델 ID, 동기 multipart POST /v1/images/edits, size: "1024x1024". 이러한 형태는 이전 초안에 나타나며 새 클라이언트에 복사하면 안 됩니다.
  • 입출력: 원본과 마스크는 POST /v1/uploads/images 로 업로드한 뒤 반환된 공개 URL 을 전달하세요. reference_images, image_urls, mask_url 은 base64 를 받지 않습니다.
  • 비동기 프로토콜: 제출 호출은 작업 id 를 반환합니다. completed 또는 failed 가 될 때까지 GET /v1/images/generations/{id} 를 폴링하세요. 클라이언트 타임아웃은 실패의 증거가 아닙니다.

2. 프로그래밍 방식 이미지 편집의 실제 가치

텍스트 프롬프트로 이미지를 생성하는 것은 첫 단계일 뿐입니다. 프로덕션 카탈로그, 광고, 디자인 시스템에서는 특정 부분만 고치는 일이 더 많습니다. 상품을 바꾸거나, 배경을 정리하거나, 정사각 패키지 컷을 와이드 히어로로 늘리면서도 조명과 피사체 정체성을 유지해야 합니다.

현재 ToAPIs GPT Image 2 계열은 이 작업을 하나의 경로, 즉 POST /v1/images/generations 에서 다루며, 차이는 모델 ID 에 있습니다.

작업모델 ID원본을 지정하는 방법마스크
프롬프트 기반 편집 또는 스타일 전환gpt-image-2reference_images(URL 목록, 최대 14)이 ID 에는 문서화되어 있지 않음
픽셀 단위 인페인팅gpt-image-2-officialimage_urls(URL 목록, 최대 16)첫 이미지와 함께 mask_url 필요
캔버스 확장(아웃페인팅)두 ID 모두 가능원본을 참고 이미지로 전달하고 size 를 목표 비율로 변경전용 outpaint 플래그 없음

정확한 gpt-image-2 에서 image_urls 는 reference_images 의 하위 호환 별칭이며 게이트웨이가 정규화합니다. 공식 채널 API 레퍼런스 예시는 image_urls 와 mask_url 을 함께 사용합니다. 실제로 호출하는 ID 의 레퍼런스 필드 이름을 따르세요.

사용 가능한 인페인팅 마스크는 알파 채널이 있는 PNG 이며, 픽셀 크기는 첫 번째 참고 이미지와 같아야 합니다. 투명 픽셀(alpha = 0)이 재생성 영역이고, 불투명 픽셀은 보존되어야 합니다. 파이프라인(예: Pillow)에서 마스크를 만든 뒤 업로드하고 URL 만 보내세요.

아웃페인팅은 워크플로이지 별도 엔드포인트가 아닙니다. 1:1 패키지 컷을 16:9 배너로 바꿔야 한다면, 원본을 참고 이미지로 유지하고, size 를 16:9 로 설정하고, resolution 티어를 명시하며, 피사체를 유지하고 장면을 확장하라고 지시하세요. 실용적인 변형은 원본을 더 큰 투명 캔버스에 합성한 뒤 업로드해 참고 이미지로 쓰는 것입니다. 그래도 경로는 /v1/images/generations 이고, outpaint: true 같은 플래그는 없습니다.

마스크 섬 형태의 프레임이 육각형 게이트웨이를 지나 확장된 캔버스로 흐르는 모습

그림 1: 원본 캔버스와 내부 마스크 영역이 ToAPIs 게이트웨이를 통과합니다. 문서화된 경로는 여전히 POST /v1/images/generations 이며, mask_url 은 gpt-image-2-official 용입니다.

size 와 resolution 은 텍스트 생성과 같은 계약을 따릅니다. size 는 1:1 또는 16:9 같은 비율이고, resolution 은 1k, 2k, 4k 입니다. 정확한 gpt-image-2 는 현재 플레이그라운드 계약에서 quality 필드를 노출하지 않습니다. quality(low / medium / high)는 gpt-image-2-official 에 나타납니다. 픽셀 표는 4K 워크플로 가이드 를 보세요.


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

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

1단계: 원본 이미지 업로드(마스크가 필요하면 함께)

bash
curl -X POST "https://api.toapis.com/v1/uploads/images" \
  -H "Authorization: Bearer $TOAPIS_API_KEY" \
  -F "file=@./product.png"

응답에 data.url 이 포함됩니다. gpt-image-2-official 을 호출할 때는 마스크 PNG 에도 같은 호출을 반복하세요. 생성 요청에 base64 를 인라인하지 마세요.

2단계: 정확한 gpt-image-2 에서 프롬프트 기반 편집

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": "Keep the ceramic kettle and slate surface. Replace only the background with a calm marble countertop, matching the existing side light. No typography.",
    "size": "1:1",
    "resolution": "1k",
    "n": 1,
    "response_format": "url",
    "reference_images": ["https://example.com/product.png"]
  }'

3단계: gpt-image-2-official 에서 마스크 인페인팅

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-official",
    "prompt": "Replace the masked region with a desert sunset, preserving the subject outline and lighting",
    "size": "1:1",
    "resolution": "1k",
    "quality": "medium",
    "image_urls": ["https://example.com/photo.png"],
    "mask_url": "https://example.com/mask.png"
  }'

4단계: Python 제출과 폴링

필드 이름은 실제로 호출하는 모델 ID 의 API 레퍼런스와 맞추세요. 아래 조각은 문서화된 이미지 상태 경로와 completed / failed 상태를 사용합니다.

python
import os
import time
import requests

API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}


def upload_image(path: str) -> str:
    with open(path, "rb") as handle:
        res = requests.post(
            f"{BASE}/v1/uploads/images",
            headers=HEADERS,
            files={"file": handle},
            timeout=60,
        )
    res.raise_for_status()
    url = res.json().get("data", {}).get("url")
    if not url:
        raise RuntimeError(f"Unexpected upload envelope: {res.text}")
    return url


def dispatch_edit(payload: dict) -> str:
    res = requests.post(
        f"{BASE}/v1/images/generations",
        headers={**HEADERS, "Content-Type": "application/json"},
        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__":
    source = upload_image("product.png")
    # Prompt-guided edit on exact gpt-image-2 (no mask field on this ID).
    task_id = dispatch_edit(
        {
            "model": "gpt-image-2",
            "prompt": "Keep the ceramic kettle; extend the scene into a wide 16:9 set with the same side light. No typography.",
            "size": "16:9",
            "resolution": "1k",
            "n": 1,
            "response_format": "url",
            "reference_images": [source],
        }
    )
    print("Task:", task_id)
    print("Image:", poll_image_task(task_id))

마스크 인페인팅으로 바꾸려면 첫 이미지와 크기가 같은 RGBA 마스크를 업로드하고, model 을 gpt-image-2-official 로 바꾼 뒤 image_urls 와 mask_url 을 보내세요. 모델 ID, size, resolution 을 작업 기록과 함께 저장해 이후 SKU 변경이 명시적인 결정이 되게 하세요.


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

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

HTTP 상태흔한 분류권장 조치
400잘못된 필드 또는 지원되지 않는 조합모델 ID, size 가 문서화된 비율인지, resolution 이 1k / 2k / 4k 인지, URL 이 공개인지를 확인하고, 마스크를 쓸 때는 gpt-image-2-official 에서 첫 이미지와 같은 크기의 알파 PNG 인지 확인하세요
401API 키 누락 또는 무효ToAPIs 대시보드에서 키를 교체하고 Authorization 헤더를 확인하세요
429속도 또는 동시성 제한Retry-After 가 있으면 따르고, 지터를 넣어 백오프하며, 안전할 때만 재시도하세요
5xx 또는 네트워크 타임아웃게이트웨이 또는 업스트림의 일시적 문제다시 제출하기 전에 작업 상태를 확인하고, 상한이 있는 재시도 정책을 쓰세요

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}

  • 기획 초안의 단가를 재사용하지 마세요. 예를 들어 고정된 $0.024 / $0.048(standard 대 HD) 조합은 현재 카탈로그 기준으로 오래되었습니다. 현재 카탈로그는 모델 ID 로 가격이 나뉘고, 표준 GPT Image 2 랜딩 비교는 해상도 티어로도 나뉩니다.
  • GPT Image 2 모델 가이드 는 현재 표준 gpt-image-2 의 ToAPIs 랜딩 비교가로 1K / 2K / 4K 에서 장당 $0.015 / $0.020 / $0.025 를 보여 줍니다. 이는 게시된 비교가이며 청구서가 아닙니다. 공식 채널 SKU 와 계정 할인은 다를 수 있으니, 실제로 호출하는 ID 의 요율을 확인하세요.
  • 라우팅(api.toapis.com 과 toapis.cn)은 베이스 URL 선택일 뿐, 문서화된 할인이 아닙니다. FinOps 이득은 1k 로 초안을 만들고, 클라이언트 타임아웃 후 중복 제출을 피하며, 올바른 SKU(gpt-image-2 와 gpt-image-2-official)를 고르는 데서 옵니다. 더 싼 "편집" 모델을 상상하지 마세요.
  • 배경은 GPT Image 2 요금 글 을 본 뒤, 예측에 넣기 전에 실시간 카탈로그로 모든 숫자를 검증하세요.

6. 자주 묻는 질문

자세한 내용은 frontmatter 의 FAQ 를 보세요. 요약: 정확한 gpt-image-2 에는 mask_url 이나 /v1/images/edits 가 문서화되어 있지 않습니다. 마스크 인페인팅은 gpt-image-2-official 에 문서화되어 있습니다. 마스크는 같은 크기의 RGBA PNG 를 URL 로 전달합니다. 아웃페인팅은 size 변경과 참고 이미지입니다. 요금은 정확한 모델 ID 로 계정에서 확인해야 합니다.


7. 액션 체크리스트

  • ToAPIs 개발자 포털 에서 키를 만드세요.
  • 환경마다 베이스 URL 을 하나 정하고(https://api.toapis.com, 필요한 경우 https://toapis.cn), POST /v1/uploads/images 로 원본 이미지를 업로드하세요.
  • gpt-image-2 에서 reference_images, size: "1:1", resolution: "1k" 로 프롬프트 기반 편집을 스모크 테스트하세요.
  • 픽셀 단위 마스크가 필요하면 gpt-image-2-official 로 전환하고, 첫 이미지와 같은 RGBA 마스크를 업로드한 뒤 image_urls 와 mask_url 을 보내세요.
  • 작업 id 를 저장하고, 제한된 시한 안에 GET /v1/images/generations/{id} 를 폴링하며, 429 에서는 Retry-After 를 지키세요.
  • 다음 읽을거리: resolution 을 올릴 때는 4K 종횡비 가이드, 더 넓은 매개변수 맵은 API 가이드.

본문에서 언급된 모델 및 API

OpenAIIMAGE

GPT-Image-2

현재 요율:3 credits /request
OpenAIIMAGE

gpt-image-2-official

현재 요율:Input 800 credits/1M, Output 4,800 credits/1M

관련 기술 블로그