---
title: 이미지 편집 API: GPT Image 모델
description: "GPT Image 편집 workflow: reference, 요청 예제, 비용 측정과 결과 검증."
url: https://apitoken.sale/ko/docs/learn/image-editing-api-guide
language: ko
---

# GPT Image 2, Flare, Sunburst로 이미지 편집

GPT Image 모델은 Images edit route에서 PNG, JPEG, WebP reference를 최대 5개 받습니다. 생성과 같은 키와 잔액을 사용하고 게시 전 결과를 검증하세요.

## GPT Image로 reference 이미지 편집

GPT Image 2, GPT Image 2.5 Flare, GPT Image 2.5 Sunburst는 같은 OpenAI Images endpoint, 키, 선불 잔액을 사용합니다. Flare는 빠른 일상 작업, Sunburst는 더 정밀한 편집에 맞습니다. 검수를 통과한 결과로 모델을 비교하세요. 세 모델의 공개 token 요금은 같습니다.

POST /v1/images/edits는 image 또는 image[]로 PNG, JPEG, WebP 파일 1~5개를 받으며 각 파일은 최대 50 MB입니다. 생성과 같은 모델 ID를 사용합니다. multipart mask는 무시되므로 부분 편집은 Responses image_generation 도구를 사용하세요. 검수 전 형상, 문구, 제품 정체성을 확인하세요.

## 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 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")},
    }],
)
```

## edit을 validated pipeline으로 실행

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

## 측정한 token 사용량으로 예산 계산

| 100만 token 사용량 | 공식 | 일반 B2C · 50% 할인 |
| --- | --- | --- |
| Text input | $5 | $2.50 |
| Cached text input | $1.25 | $0.625 |
| Image input | $8 | $4 |
| Cached image input | $2 | $1 |
| Image output | $30 | $15 |

예를 들어 fresh text input 900 token, fresh image input 1,200 token, image output 4,000 token인 편집은 공식 $0.1341, 일반 B2C $0.06705입니다. 예시 token 수는 이미지마다 보장되지 않습니다. 실제 최종 usage와 해당 요청의 차감액으로 측정하세요.

카탈로그나 batch 비용은 모든 정산 금액을 검수 통과 이미지 수로 나눕니다. 검수에 실패한 유료 결과도 포함하세요. GPT Image에는 무료 countTokens 추정기가 없으므로 소규모 유료 샘플을 측정하고 큐 시작 전 지출 한도를 설정하세요.

## 비용과 retry 규율

1. GPT Image 모델과 소규모 대표 prompt 및 reference를 선택합니다.
2. 지출 한도를 설정하고 샘플에 n=1, quality=low, size=auto를 사용합니다.
3. 거부된 결과를 포함해 모든 요청의 최종 usage와 차감액을 기록합니다.
4. 정산 금액을 검수 통과 이미지 수로 나누고 실측 비용으로 batch 예산을 정합니다.

## 자주 묻는 질문

### edit이 prompt-only generation보다 비싼가요?

billable image input이 추가되어 comparable edit은 보통 input 비용이 더 큽니다. 다만 reference가 acceptance rate를 높이고 retry를 없애면 accepted asset당 비용은 더 낮을 수 있으므로 request당이 아니라 accepted asset당 settled cost를 측정하세요.

### timeout 후 edit을 retry해도 안전한가요?

prior attempt가 accepted되지 않았음을 증명할 수 있을 때만 안전합니다. ambiguous timeout은 완료된 provider 작업을 숨길 수 있으므로 request ID를 보존하고 다음 paid attempt 전에 대조하세요. 그렇지 않으면 retry는 같은 작업의 두 번째 paid render가 됩니다.

### edit route를 저렴하게 테스트하려면?

reference 하나에 n=1, quality=low, size=auto로 시작하세요. 작업량 확대 전 반환 크기와 최종 usage를 확인하세요.

### 어떤 reference 이미지를 보낼 수 있나요?

/v1/images/edits의 image 또는 image[]로 PNG, JPEG, WebP 1~5개를 보냅니다. 각 파일은 최대 50 MB입니다.

---
Get a key: https://apitoken.sale/register
More guides: https://apitoken.sale/ko/docs/learn