이미지 변환(이미지 편집)

POST /v1/images/edits image-to-image endpoint는 multipart/form-data request body를 사용합니다. 하나 이상의 reference images를 업로드하고 prompt 및 parameter fields를 form fields로 제출하세요.

https://bettertoken.ai/v1을 Base URL로 사용하세요. Authorization: Bearer YOUR_API_KEY를 통해 BetterToken API Key를 전달하세요.

페이지 오른쪽의 Playground에서 form fields를 입력하고 reference images를 업로드한 다음 https://bettertoken.ai/v1/images/edits로 request를 직접 보낼 수 있습니다.

image-to-image requests에 일반 JSON body를 사용하지 마세요. text fields와 file fields는 multipart/form-data로 제출하세요.

권장 값

모든 request에서 다음 fields를 명시적으로 보내세요.

model=gpt-image-2
n=1
response_format=b64_json
output_format=png

단일 reference image에는 image를 사용하세요. 여러 reference images에는 반복된 image[] fields를 사용하세요.

단일 reference image

curl 'https://bettertoken.ai/v1/images/edits' \
  -H 'Authorization: Bearer sk-***REDACTED***' \
  -F 'model=gpt-image-2' \
  -F 'prompt=Use this reference image to create a more polished square product hero image while keeping the main style consistent.' \
  -F 'n=1' \
  -F 'size=1024x1024' \
  -F 'response_format=b64_json' \
  -F 'output_format=png' \
  -F 'image=@reference.png'

여러 reference images

curl 'https://bettertoken.ai/v1/images/edits' \
  -H 'Authorization: Bearer sk-***REDACTED***' \
  -F 'model=gpt-image-2' \
  -F 'prompt=Combine these reference images into one consistent promotional poster.' \
  -F 'n=1' \
  -F 'size=1024x1024' \
  -F 'response_format=b64_json' \
  -F 'output_format=png' \
  -F 'image[]=@reference-1.png' \
  -F 'image[]=@reference-2.jpg' \
  -F 'image[]=@reference-3.png'

mask로 선택 영역 편집

선택한 영역을 중심으로 편집하려면 선택 사항인 mask 파일 필드를 추가하세요. 현재 BetterToken endpoint는 하나의 mask 파일만 읽습니다. mask[] 필드를 여러 번 보내지 마세요.

원본 이미지와 mask는 파일 형식과 픽셀 크기가 같아야 합니다. 각 파일은 50 MB보다 작아야 합니다. 최대 호환성을 위해 두 파일 모두 Alpha channel이 있는 PNG를 사용하세요.
Mask에는 Alpha channel이 있어야 합니다. 완전히 투명한 픽셀(Alpha 0)은 모델이 다시 그릴 수 있는 영역을 표시합니다. 완전히 불투명한 픽셀(Alpha 255)은 해당 영역을 유지하도록 모델을 유도합니다.
일반 RGB 흑백 이미지는 실제 Alpha channel을 포함하지 않으면 유효한 mask가 아닙니다.
여러 image[] 필드를 보내면 mask는 첫 번째 입력 이미지에 적용됩니다.
Mask는 모델을 안내하지만, 투명 영역 밖의 픽셀이 완전히 동일하게 유지된다고 보장하지는 않습니다.

curl 'https://bettertoken.ai/v1/images/edits' \
  -H 'Authorization: Bearer sk-***REDACTED***' \
  -F 'model=gpt-image-2' \
  -F 'prompt=Replace only the masked area with a blue circle. Preserve everything else.' \
  -F 'n=1' \
  -F 'size=1024x1024' \
  -F 'response_format=b64_json' \
  -F 'output_format=png' \
  -F 'image=@original.png' \
  -F 'mask=@mask.png'

Python masked edit

요청 후 Python이 두 파일을 닫도록 하나의 with 문에서 파일을 여세요.

import requests

url = "https://bettertoken.ai/v1/images/edits"
headers = {"Authorization": "Bearer sk-***REDACTED***"}
data = {
    "model": "gpt-image-2",
    "prompt": "Replace only the masked area with a blue circle. Preserve everything else.",
    "n": "1",
    "size": "1024x1024",
    "response_format": "b64_json",
    "output_format": "png",
}

with open("original.png", "rb") as image_file, open("mask.png", "rb") as mask_file:
    files = {
        "image": ("original.png", image_file, "image/png"),
        "mask": ("mask.png", mask_file, "image/png"),
    }
    response = requests.post(url, headers=headers, data=data, files=files, timeout=300)

response.raise_for_status()
result = response.json()

upload 전 파일 확인

이 최소 Pillow 검사는 필수 형식, 크기, Alpha channel을 확인합니다. 일반적인 local mask의 경우 Alpha channel에 완전히 투명한 영역과 완전히 불투명한 영역이 모두 없으면 경고도 표시합니다.

from pathlib import Path
from PIL import Image

image_path = Path("original.png")
mask_path = Path("mask.png")

if image_path.stat().st_size >= 50 * 1024 * 1024 or mask_path.stat().st_size >= 50 * 1024 * 1024:
    raise ValueError("Each file must be smaller than 50 MB")

with Image.open(image_path) as image, Image.open(mask_path) as mask:
    if image.format != mask.format:
        raise ValueError("The image and mask formats must match")
    if image.size != mask.size:
        raise ValueError("The image and mask dimensions must match")
    if "A" not in mask.getbands():
        raise ValueError("The mask must contain an Alpha channel")
    alpha_min, alpha_max = mask.getchannel("A").getextrema()
    if alpha_min > 0 or alpha_max < 255:
        print("Warning: for a typical local mask, include fully transparent and fully opaque areas")

Python 예시

import requests

url = "https://bettertoken.ai/v1/images/edits"
headers = {
    "Authorization": "Bearer sk-***REDACTED***",
}

data = {
    "model": "gpt-image-2",
    "prompt": "Use this reference image to create a more polished square product hero image while keeping the main style consistent.",
    "n": "1",
    "size": "1024x1024",
    "response_format": "b64_json",
    "output_format": "png",
}

with open("reference.png", "rb") as image_file:
    files = {
        "image": ("reference.png", image_file, "image/png"),
    }
    response = requests.post(url, headers=headers, data=data, files=files, timeout=300)

response.raise_for_status()
result = response.json()
b64_json = result["data"][0]["b64_json"]

권장 sizes

`size`	비율	사용 사례
`auto`	자동	자동 size 선택
`1024x1024`	`1:1`	정사각형 images, avatars, covers, assets
`1536x1024`	`3:2`	가로 posters, banners, scenes
`1024x1536`	`2:3`	세로 mobile covers 및 posters
`1536x1152`	`4:3`	표준 가로 images, product images, content graphics
`1152x1536`	`3:4`	표준 세로 images, mobile covers, vertical posters
`2048x2048`	`1:1`	고해상도 정사각형 images
`2048x1152`	`16:9`	고해상도 가로 images
`3840x2160`	`16:9`	4K 가로 images
`2160x3840`	`9:16`	4K 세로 images

size는 예상 aspect ratio와 size tier를 나타냅니다. 실제 반환 pixels는 server에 의해 mapping 또는 adjusted될 수 있습니다. output을 요청한 값으로 강제로 crop하지 말고 decoded image dimensions를 사용하세요.

이미지 저장

성공한 response는 다음 OpenAI-compatible image response shape를 따릅니다.

{
  "created": 1710000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...(truncated)"
    }
  ]
}

data[0].b64_json을 읽어 base64 image content로 저장하세요. 항상 output_format: "png"를 설정하면 decoded image를 .png로 저장할 수 있습니다.

Response flow

이 endpoint는 synchronous입니다. POST /images/edits를 보낸 후 server가 response할 때까지 현재 HTTP request를 열어 두세요. generation에 성공하면 image content가 data[0].b64_json으로 반환됩니다. endpoint는 task_id를 반환하지 않으며 별도의 status query 또는 result download endpoint가 없습니다.

GPT Image 2

이미지 변환(이미지 편집)

권장 값

단일 reference image

여러 reference images

mask로 선택 영역 편집

Python masked edit

upload 전 파일 확인

Python 예시

권장 sizes

이미지 저장

Response flow

관련 문서

인증

본문

응답

​권장 값

​단일 reference image

​여러 reference images

​mask로 선택 영역 편집

​Python masked edit

​upload 전 파일 확인

​Python 예시

​권장 sizes

​이미지 저장

​Response flow

​관련 문서

인증

본문

응답

권장 값

단일 reference image

여러 reference images

mask로 선택 영역 편집

Python masked edit

upload 전 파일 확인

Python 예시

권장 sizes

이미지 저장

Response flow

관련 문서