GPT Image의 1K, 2K, 4K, Quality, Mask 사용법: BetterToken 실측 가이드

• 같은 모델과 같은 매개변수인데도 호출할 때마다 결과가 다른 이유는 무엇인가요?
• 4K나 특정 크기를 지정했는데 결과 이미지가 1K로 축소되는 이유는 무엇인가요?
• Mask 부분 수정이나 quality=high가 실제로 적용되나요? 최종 요금은 어떤 기준으로 청구되나요?

참고: 이 문서는 gpt-image-2, gpt-image-2.5-flare, gpt-image-2.5-sunburst에 초점을 맞춥니다. Nano Banana 시리즈는 매개변수와 요금 체계가 다르므로 혼동을 피하기 위해 별도 문서에서 자세히 다룹니다.

​

1. 같은 모델과 같은 매개변수인데 결과가 달라질 수 있는 이유는 무엇인가요?

​

2. 테스트 방법: ‘지원’을 어떻게 판정하나요?

1. 원본 파일 픽셀 디코딩: 인터페이스 선언만 믿지 않습니다. 전달된 이미지마다 원본 파일 내용을 디코딩해 가로·세로를 확인하고, 응답의 청구 등급 및 계정의 실제 차감액과 대조합니다.
2. 크기 달성 판정: 명시적으로 지정한 너비와 높이를 각각 비교합니다. 실제 반환 크기가 더 크면 통과로 봅니다. 어느 한쪽이라도 목표 크기보다 5% 넘게 작으면 미달로 판정합니다(참고: 이 기준은 테스트 결과를 엄격하게 평가하기 위한 것이며, API가 크기에 미달한 유효 이미지를 자동으로 폐기한다는 뜻은 아닙니다). 크기를 생략하거나 auto를 전달한 경우에는 고정 캔버스 목표가 없는 것으로 봅니다.
3. 매개변수 수락과 실제 효과 구분: 인터페이스에서 오류가 발생하지 않았다는 것은 매개변수가 “수락됨”을 뜻할 뿐입니다. Mask가 영역을 엄격히 분리하는지, quality=high가 눈에 띄는 개선을 제공하는지는 최종 이미지를 확인해야 합니다.

​

3. 실측 결과: 어떤 매개변수가 가장 자주 오해되나요?

• 기본 매개변수 허용: quality와 size를 생략하거나 null로 전달하거나 명시적으로 "auto"를 지정해도 정상적으로 이미지가 생성됩니다.
• 올바른 4K 요청 방법: “4K”는 청구 등급 개념이며 4096x4096 정사각형 지원을 의미하지 않습니다. 4K급 고해상도 가로 이미지를 원하면 3840x2160을 사용하세요.
• 잘못된 매개변수 무과금 차단: 4096x4096, stream=true, 빈 문자열 quality="", 빈 문자열 size="", n=0을 전달한 모든 테스트 요청은 HTTP 400 오류를 반환했고 요금이 전혀 청구되지 않았습니다.

​

4. BetterToken이 제공하는 기능: 경로별로 직접 대응할 필요가 없습니다

1. 기능 기반 지능형 라우팅: 전달된 모델, 목표 크기(예: 2K/4K), 이미지 편집 또는 Mask 매개변수 포함 여부에 따라 해당 기능을 갖춘 사용 가능한 서비스를 자동 선택합니다.
2. 통합 인터페이스와 매개변수 기본 처리: 표준 POST /v1/images/generations(이미지 생성) 및 POST /v1/images/edits(참조 이미지/Mask 편집) 인터페이스가 null, auto, 누락된 매개변수를 자동 처리하며 잘못된 입력은 게이트웨이에서 바로 차단합니다.
3. 실제 크기와 청구 내역의 투명한 반환: 이미지 데이터와 함께 응답 본문의 bettertoken_image_billing 필드에서 **실제 디코딩 너비·높이(width/height), 청구 등급(billing_resolution), 통화 및 정산 금액(settled_amount)**을 확인할 수 있습니다.
4. 핵심 개념 두 가지를 명확히 구분:
   • Mask 매개변수 지원 ≠ 픽셀 단위의 정밀한 리터치 보장: 인터페이스는 참조 이미지와 Mask 업로드를 통한 편집을 지원하지만, 일부 실측 결과에서는 마스크 외부의 보호 영역도 수정되었습니다. 예를 들어 기하학적 두 원 테스트에서는 왼쪽 투명 원은 색상을 바꾸고 오른쪽 불투명 원은 보호하도록 요청했지만 두 원 모두 색이 바뀌었습니다. 따라서 Mask 매개변수 전달은 지원하지만 매번 픽셀 단위의 엄격한 영역 분리를 보장하지는 않습니다.
   • quality 매개변수 지원 ≠ 고정된 화질 향상 폭 보장: 인터페이스는 "auto", "high" 등의 매개변수를 지원하고 올바르게 라우팅합니다. 그러나 이미지 생성에는 무작위성이 있으므로 단일 샘플만으로 high가 일정 비율의 화질 향상을 제공한다고 과도하게 약속하지 않습니다.

⚠️ 연동 전에 알아야 할 실제 한계 두 가지:

1. 기능 기반 라우팅이 매번 픽셀을 엄격하게 고정한다는 뜻은 아닙니다: 기반 서비스 출력 차이로 인해 올바른 노드로 라우팅되어도 실제 픽셀은 달라질 수 있습니다(예: 오늘 1024x1024 요청 중 1024×936 반환 사례가 있었고, 3840x2160 요청에서 3840×2161을 반환한 샘플이 있었습니다). 비즈니스에서 캔버스 비율이 매우 중요하다면 응답의 실제 너비와 높이에 따라 자르거나 후처리하세요.
2. 1K를 요청해도 반드시 1K 요금이 청구되는 것은 아닙니다: 과금 시스템은 실제로 전달된 유효 이미지의 규격으로 등급을 정합니다. 오늘 두 2.5 모델(일부 gpt-image-2 사례 포함)은 1024x1024 요청에 1254×1254를 반환했습니다. 시스템은 이를 2K로 판정해 해당 요금을 청구합니다.

​

5. 세 모델의 지원 현황: 어떤 모델을 호출하고 어떤 값을 전달해야 하나요?

​

6. 실제 이미지 사례 두 가지: 결과는 어떨까요?

​

사례 A: 전자상거래 상품 사진, 1K / 2K / 4K 크기 및 세부 묘사

실제 전자상거래 스튜디오 사진을 생성합니다. 산호색 빨간 세라믹 머그컵(손잡이는 오른쪽)이 옅은 회색 석재 테이블 위에 놓여 있고 왼쪽에는 접힌 베이지색 리넨 천이 있습니다. 컵에는 선명한 흰색 글자 “BETTER DAY”가 인쇄되어 있습니다. 왼쪽 위에서 부드러운 측면광이 비치며 도자기 유약의 미묘한 반사, 리넨 섬유와 자연스러운 접촉 그림자를 살립니다. 컵 전체가 프레임 안에 들어오고 중앙에 배치됩니다. 배경은 단순하고 중성적이며 다른 물체, 워터마크, 추가 문자는 없습니다.

Photorealistic ecommerce studio photograph. A coral-red ceramic mug with a handle on the right sits on a pale gray stone tabletop, with a folded beige linen cloth to its left. The mug reads "BETTER DAY" in clear white lettering. Soft directional light from upper left, subtle glaze reflections, visible linen fibers and natural contact shadows. Entire mug in frame, centered composition, simple neutral background. No other objects, no watermark, no additional text.

• 완성도 높은 화면: 세 이미지 모두 산호색 유약의 반사, 오른쪽 손잡이, 옅은 회색 석재 테이블, 베이지색 리넨 섬유, 선명하고 읽기 쉬운 흰색 “BETTER DAY”를 표현했습니다.
• 독립 샘플 간 차이: 매 생성은 독립적인 샘플링이므로 컵의 통통한 정도, 글자 굵기, 천을 접은 모양에 자연스러운 차이가 있습니다(예: 4K 가로 이미지에서는 문자가 두 줄로 배치됨). 따라서 부분 크롭은 각 이미지의 실제 세부 묘사를 보여줄 뿐이며, 구도가 엄격히 동일한 광학 선명도 실험은 아닙니다.
• 요금 경계가 직접 드러남: 첫 번째 이미지는 1024x1024를 요청했지만 실제로 1254×1254의 고해상도 정사각형 이미지가 전달되어 두 번째 2048×2048 이미지와 마찬가지로 **2K 등급(¥0.11)**으로 청구되었습니다.

​

사례 B: 상품의 부분 색상 변경, Mask의 실제 효과와 한계

투명 마스크 영역 안의 산호색 컵 몸체만 짙은 네이비 블루로 바꿉니다. 세라믹 재질, 조명과 반사를 유지합니다. 흰색 “BETTER DAY” 글자, 빨간 손잡이, 리넨 천, 테이블 상판, 배경과 전체 구도를 변경하지 않습니다. 물체를 추가하거나 제거하지 않습니다.

Change only the coral-red mug body inside the transparent mask to deep navy blue. Preserve ceramic texture, lighting and reflections. Keep the white "BETTER DAY" lettering, red handle, linen cloth, tabletop, background and composition unchanged. Do not add or remove any objects. Do not change anything outside the transparent mask.

• 핵심 색상 변경 의도 달성: 머그컵 바깥 몸체가 짙은 네이비 블루로 바뀌었고 세라믹 하이라이트 질감은 유지됐습니다. 마스크 밖의 빨간 손잡이, 왼쪽 리넨 천, 배경은 전반적으로 유지됐고 마스크 안의 “BETTER DAY” 글자도 읽을 수 있었습니다.
• 엄격한 Mask 경계는 통과하지 못함(영역 침범 발생): 컵 가장자리와 안쪽 벽면을 자세히 보면 원래 불투명 보호 영역이었던 산호색 부분도 모델이 짙은 파란색으로 함께 바꿨습니다. 더 극단적인 ‘두 원’ 기하학 테스트에서도 마스크가 적용되지 않은 오른쪽 원의 색이 바뀌었습니다.
• 사용 권장 사항: 참조 이미지와 Mask를 업로드할 때 두 이미지의 캔버스 크기를 동일하게 맞추고(수정할 곳은 투명, 보존할 곳은 불투명), Prompt에 “무엇을 바꿀지”와 “무엇을 보존할지”를 모두 명시하세요. 브랜드 로고, 포장지의 작은 글자, 엄격한 경계가 필요한 산업용 상업 이미지라면 생성 후 확대해 보호 영역 경계를 반드시 확인하세요.

​

7. 가격과 실제 사용 비용: 최종 청구액은 얼마인가요?

💡 예산 계획의 핵심: ‘요청 매개변수’가 아니라 ‘실제 전달 등급’을 기준으로 비용을 계산하세요. 앞선 실측에서 보듯 오늘 flare, sunburst 또는 gpt-image-2에 1024x1024(1K)를 요청한 일부 호출은 1254×1254 이미지를 전달했습니다. 이 경우 시스템은 실제 결과를 기준으로 2K로 분류합니다(즉 1K 가격 ¥0.035가 아니라 ¥0.15 또는 ¥0.11이 청구됨). flare의 1024x1024 요청 100건이 모두 1254×1254를 반환한다면 현재 단가 기준 100장의 비용은 **¥15.00(산술 추정)**입니다. 또한 시스템의 등급 판정은 목표 크기와 합리적인 편차 임계값을 함께 고려합니다(예: 3840×2159는 일반적으로 4K, 1536×1024는 1K로 분류). 비즈니스 애플리케이션에서 “긴 변이 1024보다 큰가” 같은 단순 규칙으로 비용을 다시 계산하지 마세요. 최종 정산은 항상 응답 본문의 bettertoken_image_billing 필드를 기준으로 합니다.

​

표면적인 ‘이미지당 저렴한 가격’만 보면 안 되는 이유

1. 실제 반환 크기가 목표에 도달해야 가격을 비교할 수 있습니다: “4K 지원 및 매우 저렴한 가격”을 내세워도 실제로 1024 크기의 축소 이미지만 반환한다면 고해상도 이미지가 필요한 프로덕션 환경에서 사용할 수 없으므로 유효한 4K 가격 비교 대상이 아닙니다.
2. 실패와 재작업 비용을 총액에 포함하세요: 이번 잘못된 매개변수 테스트는 과금되지 않았습니다. 이미지가 성공적으로 전달됐지만 결과가 만족스럽지 않아 다시 요청하는 경우에는 별도의 새 요청이므로 따로 예산을 책정해야 합니다. 이 문서의 상품 및 Mask 사례 이미지 4장(생성 3장 + 편집 1장)은 모두 한 번의 요청으로 전달됐습니다. Mask 샘플에는 위에서 설명한 영역 침범 색상 변경이 있었습니다. 각 이미지의 단가는 ¥0.11, ¥0.11, ¥0.13, ¥0.11이며 이미지 4장의 실제 총비용은 ¥0.46에 불과했습니다. 청구 내역은 계정 차감액과 정확히 일치했습니다. 경로가 불안정하거나 매개변수가 호환되지 않아 여러 번 다시 생성하면 표면적인 장당 가격이 낮더라도 실제 사용 가능한 소재 한 장을 얻는 종합 비용은 증가할 수 있습니다.
3. 숨겨진 개발 적응 비용을 절감하세요: BetterToken은 매개변수 규격을 통일하고 기능에 따라 지능형 라우팅하며 실제 픽셀과 청구 필드를 실시간 반환해, 서비스마다 개별 대응하고 크기와 비용 정보를 직접 정리하는 개발 작업을 줄입니다.

​

8. 바로 복사해 쓸 수 있는 호출 예시

​

예시 1: JSON 요청으로 고해상도 상품 이미지 생성 (POST /v1/images/generations)

curl https://bettertoken.ai/v1/images/generations -o response.json \
  -H "Authorization: Bearer $BETTERTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "model": "gpt-image-2",
  "prompt": "Photorealistic ecommerce studio photograph. A coral-red ceramic mug with a handle on the right sits on a pale gray stone tabletop, with a folded beige linen cloth to its left. The mug reads \"BETTER DAY\" in clear white lettering. Soft directional light from upper left, subtle glaze reflections, visible linen fibers and natural contact shadows. Entire mug in frame, centered composition, simple neutral background. No other objects, no watermark, no additional text.",
  "size": "2048x2048",
  "quality": "high",
  "n": 1,
  "response_format": "b64_json",
  "output_format": "png"
}
JSON

• 크기 규격 참고: 4K 가로 이미지를 원하면 "size"를 "3840x2160"으로 바꾸세요("4096x4096"은 사용하지 마세요). 현재 유효한 크기는 다음 조건을 충족해야 합니다. 너비와 높이는 모두 16의 배수, 긴 변은 3840 이하, 긴 변과 짧은 변의 비율은 3:1 이하, 전체 픽셀 수는 655,360에서 8,294,400 사이입니다.
• 파일 형식 식별 참고: 요청에서 "output_format": "png"를 지정해도 일부 기반 노드가 JPEG 형식의 바이너리를 반환할 수 있습니다. 이미지 저장 또는 처리 시 파일 확장자를 고정하지 말고 파일 헤더(Magic Bytes)로 실제 형식을 식별하는 것이 좋습니다.

​

예시 2: Multipart 참조 이미지 및 Mask 부분 편집 (POST /v1/images/edits)

curl https://bettertoken.ai/v1/images/edits -o response.json \
  -H "Authorization: Bearer $BETTERTOKEN_API_KEY" \
  -F "model=gpt-image-2" \
  -F "image=@product-1k-0.png;type=image/png" \
  -F "mask=@mask-mug.png;type=image/png" \
  -F 'prompt=Change only the coral-red mug body inside the transparent mask to deep navy blue. Preserve ceramic texture, lighting and reflections. Keep the white "BETTER DAY" lettering, red handle, linen cloth, tabletop, background and composition unchanged. Do not add or remove any objects. Do not change anything outside the transparent mask.' \
  -F "size=2048x2048" \
  -F "quality=high" \
  -F "n=1" \
  -F "response_format=b64_json"

​

예시 3: 실제 전달 픽셀과 청구 정보 읽기(응답 구조 및 파싱 코드)

{
  "created": 1792398084,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ],
  "bettertoken_image_billing": {
    "currency": "CNY",
    "settled_amount": "0.11",
    "outputs": [
      {
        "index": 0,
        "width": 2048,
        "height": 2048,
        "billing_resolution": "2K",
        "currency": "CNY",
        "amount": "0.11"
      }
    ]
  }
}

import base64
import io
import json
from pathlib import Path
from PIL import Image  # 需要 Pillow

# 将 API 的 JSON 响应保存为 response.json 后执行。
resp_json = json.loads(Path("response.json").read_text())
if "error" in resp_json:
    raise RuntimeError(resp_json["error"])

billing = resp_json["bettertoken_image_billing"]
outputs = {item["index"]: item for item in billing["outputs"]}
for index, item in enumerate(resp_json["data"]):
    img_bytes = base64.b64decode(item["b64_json"], validate=True)
    with Image.open(io.BytesIO(img_bytes)) as image:
        image.load()
        width, height = image.size
        ext = {"PNG": "png", "JPEG": "jpg", "WEBP": "webp"}.get(image.format)
        if ext is None:
            raise ValueError(f"未处理的图片格式：{image.format}")
    Path(f"output_{index}.{ext}").write_bytes(img_bytes)
    info = outputs[index]
    print(f"图片 {index}：原图 {width}×{height}；计费档位 {info['billing_resolution']}")
    print(f"单张费用：{info['amount']} {info['currency']}")
    if (width, height) != (info["width"], info["height"]):
        print("图片像素与响应尺寸不一致，请保留结果并联系支持。")
print(f"本次结算：{billing['settled_amount']} {billing['currency']}")

• OpenAI 공식 문서: 이미지 프롬프트 작성 가이드(Image Prompting Guide)
• OpenAI Cookbook: 입력 이미지 고충실도 생성 및 편집 예시