GPT Image 2 또는 Nano Banana 2로 이미지 편집

reference contract에 맞는 route 선택

이미지 편집은 reference image를 billable input으로 싣고 prompt에 허용된 변경 하나만 명시하는 generation request입니다. apiToken.sale prepaid key 하나로 두 production edit route를 쓸 수 있습니다. OpenAI Images edits endpoint의 GPT Image 2는 PNG, JPEG, WebP reference 1~5장(각 ≤50 MB)을 받아 non-streaming base64 PNG 한 장을 반환하고, native Gemini generateContent route의 Nano Banana 2(모델 gemini-3.1-flash-image)는 PNG, JPEG, WEBP, HEIC, HEIF reference를 최대 14장 받아 inlineData image part로 응답합니다. 브랜드 선호가 아니라 애플리케이션이 검증할 수 있는 reference contract로 결정하세요.

두 protocol은 교환할 수 없습니다. OpenAI Images schema용 client는 Gemini inlineData response를 파싱할 수 없습니다. GPT Image 2 edit는 50 MB 이하 PNG, JPEG, WebP를 받고 여전히 PNG 한 장을 반환합니다. 설계 단계에서 asset class별로 route를 고정하세요. retry loop 안에서 protocol을 바꾸면 output 파싱과 cost attribution이 모두 깨집니다.

함께 보기: GPT Image 2 API로 이미지 생성 및 편집

GPT Image 2 edit: PNG, JPEG, WebP 입력, base64 PNG 한 장 출력

edits endpoint는 multipart form data입니다. model, prompt, reference당 image 필드 하나씩입니다. 공개 profile은 background opaque 또는 transparent, quality low, 비율 size(auto, 1024x1024/1:1, 1536x1024/3:2, 1024x1536/2:3, 4:3, 16:9, 9:16)입니다. response는 base64 PNG 한 장의 JSON입니다. 2K/4K 등 다른 pixel size는 거부됩니다.

curl https://router.apitoken.sale/v1/images/edits \
  -H "Authorization: Bearer $APITOKEN_API_KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=Replace only the background with a neutral studio backdrop; keep the product untouched" \
  -F "image=@reference.png;type=image/png" \
  -F "background=opaque" \
  -F "quality=low" \
  -F "size=auto"

reference마다 필드 이름 image를 반복하거나 image[]를 보내세요. /v1/images/edits의 multipart mask는 무시됩니다. 인페인트는 Responses input_image_mask입니다.

// Response (abridged): decode data[0].b64_json into a PNG file.
{
  "data": [
    { "b64_json": "<BASE64 PNG>" }
  ]
}

payload decode가 request의 끝이 아닙니다. request ID와 terminal usage를 source 및 result 파일과 함께 저장하세요. PNG byte 크기는 과금 공식이 아니며 billing authority는 terminal usage event이고 dashboard charge도 이것과 대조됩니다.

영역 inpaint: Responses 마스크, Images mask 아님

POST /v1/images/edits의 multipart mask 필드는 거부됩니다. 이 ChatGPT 풀에서는 그 OpenAI Images 형태를 쓸 수 없습니다. 일부만 바꾸거나 GPT 텍스트 모델에서 hosted image_generation을 쓰려면 POST /v1/responses를 호출하세요(Chat Completions가 같은 도구를 매핑). 원본 PNG는 input의 input_image이고 tools: [{type:"image_generation", …}]입니다. 마스크는 input_image_mask.image_url을 data:image/png;base64,…로 둡니다. 마스크는 원본과 같은 크기여야 합니다. 투명 픽셀이 수정 영역입니다. Responses는 output_format jpeg/webp와 partial_images 1..=3(SSE response.image_generation_call.partial_image)도 전달하며 background=transparent는 opaque로, input_fidelity는 제거됩니다. file_id는 실패합니다. 정산은 image token 기준이며 마스크는 두 번째 reference가 아닙니다. 별도 POST /v1/images/*는 여전히 non-streaming PNG만 반환합니다.

import base64, os
from pathlib import Path
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["APITOKEN_API_KEY"],
    base_url="https://router.apitoken.sale/v1",
)

def png_url(path):
    return "data:image/png;base64," + base64.b64encode(Path(path).read_bytes()).decode()

response = client.responses.create(
    model="gpt-5.6-sol",
    input=[{
        "role": "user",
        "content": [
            {"type": "input_text", "text": "Change only the masked region."},
            {"type": "input_image", "image_url": png_url("photo.png")},
        ],
    }],
    tools=[{
        "type": "image_generation",
        "output_format": "webp",
        "partial_images": 2,
        "input_image_mask": {"image_url": png_url("mask.png")},
    }],
)

Nano Banana 2 edit: multimodal input으로서의 reference

Nano Banana 2에는 별도 edits endpoint가 없습니다. edit은 parts 배열에 instruction text와 reference당 inline_data part 하나씩을 섞는 일반 generateContent 호출이며 최대 14개 지원 이미지를 받습니다. reference가 그저 또 다른 part이므로 JPEG/WEBP 카탈로그 사진을 변환 없이 볼 수 있어 source archive가 PNG가 아닐 때 pipeline이 실제로 단순해집니다.

curl https://router.apitoken.sale/v1beta/models/gemini-3.1-flash-image:generateContent \
  -H "x-goog-api-key: $APITOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d @edit-request.json

// edit-request.json
{
  "contents": [{
    "parts": [
      { "text": "Replace only the background with a neutral studio backdrop; keep the product untouched" },
      { "inline_data": { "mime_type": "image/jpeg", "data": "<BASE64 REFERENCE>" } }
    ]
  }],
  "generationConfig": {
    "responseModalities": ["TEXT", "IMAGE"],
    "imageConfig": { "imageSize": "1K", "aspectRatio": "1:1" }
  }
}

generationConfig가 output contract를 고정합니다. responseModalities는 TEXT와 IMAGE, imageSize는 0.5K/1K/2K/4K 중 하나, aspect ratio는 공개된 값 중 하나입니다. response는 자체 parts 배열을 담고 이미지는 MIME type과 base64 payload를 가진 inlineData part로 도착하며 text part와 함께 올 수 있습니다. 가장 저렴한 live 크기는 0.5K 또는 512이며 subscription wire는 512를 사용합니다.

edit을 validated pipeline으로 실행

1. 01모든 reference를 server-side에서 정규화·검사합니다. 파일을 decode하고 supported MIME type을 확인한 뒤 paid call 전에 empty/oversized payload를 거부합니다.
2. 02edit brief에서 product geometry, logo, label text 같은 immutable trait와 단일 named change를 분리합니다. request당 변경 하나여야 failure를 진단할 수 있습니다.
3. 03client가 decode할 수 있는 output contract의 route를 고르고 inlineData parsing과 OpenAI Images parsing을 절대 섞지 않습니다.
4. 04source asset당 bounded candidate 하나만 본내고 첫 output이 review를 통과하기 전에 paid variant를 늘리지 않습니다.
5. 05downstream이 보기 전에 delivered image의 format, plausible dimensions, product identity, prohibited change 부재를 검증합니다.
6. 06request ID, terminal usage, prompt version, source, result를 함께 저장합니다. 이 기록이 rollback path이자 cost attribution입니다.

공개 요금으로 edit 비용 계산

일반 B2C 계정에서 두 모델 모두 official usage total의 정확히 50%로 과금됩니다. GPT Image 2는 token 단위로 정산합니다. 할인 후 fresh text input은 1M당 $2.50, fresh image input은 1M당 $4, image output은 1M당 $15이며 cached input은 할인 전 fresh 요금의 1/4로 인정됩니다. 첨부하는 reference마다 billable image input이므로 reference 수는 quality control이면서 cost control입니다.

첫 행의 token 수는 요금이 아닌 예시입니다. GPT Image 2 output usage는 요청마다 달라지며 terminal usage만이 권위입니다. Nano Banana 2는 반대 구조로 image-output leg가 크기별로 고정되고(B2C 할인 후 1K $0.0336, 2K $0.0504, 4K $0.0756) text input, reference image input, text/thinking output은 가변입니다. edit은 보통 prompt-only generation보다 input 비용이 크지만 좋은 reference가 acceptance rate를 높이고 retry를 없애면 회수됩니다.

edit bill을 구성하는 모든 token 요금 설명 →

비용과 retry 규율

• requested edit을 제약하는 reference만 본내세요. 두 route 모두 각각이 billable image input입니다.
• ambiguous timeout 후 edit을 자동 replay하지 마세요. provider가 작업을 완료했을 수 있고 blind retry는 두 번째 paid render입니다. 먼저 request ID로 대조하세요.
• source asset당 variant와 attempt를 제한하고 quality gate가 loop를 끝내게 하세요. 50% 할인은 낭비 비용을 반으로 줄일 뿐 없애지 않습니다.
• image-editing worker에 experiment과 분리된 lifetime spending limit이 있는 전용 key를 발급해 batch bug가 공유 잔액을 소진하지 못하게 하세요.
• 쓰기 전에 추정하세요. gemini-3.1-flash-image의 countTokens는 input을 무료로 측정하고 Google/GitHub로 만든 새 계정의 $5 welcome bonus는 초기 pipeline 테스트를 충분히 커버합니다.

자주 묻는 질문

관련 가이드