Skip to main content
POST
Image Edit: edit or fuse reference images by instruction
오른쪽의 인터랙티브 플레이그라운드는 직접적인 로컬 이미지 업로드를 지원합니다. Authorization에 API Key를 입력하고(형식: Bearer sk-xxx), 이미지 / 마스크 파일을 선택한 다음, promptmodel를 입력하고 전송하십시오.
사용 사례: 이 페이지는 “하나 이상의 참조 이미지를 기반으로 한 편집 / 합성 / 인페인트”용입니다. 요청 형식은 multipart/form-data입니다. 순수 텍스트-이미지 생성을 원하시면 텍스트-이미지 엔드포인트를 사용하십시오.
🖥️ 브라우저 플레이그라운드 제한(중요)이 엔드포인트는 응답으로 raw base64 문자열(일반적으로 수 MB)을 반환합니다. 브라우저 렌더링 제한 때문에, 응답이 도착한 후 오른쪽의 플레이그라운드에 请求时发生错误: unable to complete request이 표시될 수 있습니다. 실제로 요청은 성공한 것입니다; 브라우저가 이렇게 긴 base64 문자열을 렌더링할 수 없을 뿐입니다.권장 워크플로(초보자 친화적):
  • 아래의 Python / Node.js / cURL 샘플을 복사하여 로컬에서 실행하십시오. 코드는 응답을 자동으로 base64.b64decode하고 이미지를 파일로 저장합니다.
  • 브라우저 내 플레이그라운드를 반드시 사용해야 한다면, **아주 작은 참조 이미지(< 50KB)**를 사용하고, size를 가장 작은 단계(예: 1024x1024)로 설정한 뒤, qualitylow로 설정하십시오.
⚠️ 핵심 차이점(gpt-image-1.5에서 이전하는 경우)
  • input_fidelity를 전달하지 마십시오gpt-image-2가 고정밀을 강제하므로, 전달하면 400이 반환됩니다
  • 편집 요청의 입력 tokens가 눈에 띄게 더 많습니다 — 참조 이미지는 Vision 과금을 통해 많은 tokens으로 변환되므로, 이에 맞게 예산을 잡으십시오
  • background: transparent는 지원되지 않습니다opaque를 사용하거나 후처리하십시오
  • 다중 이미지 융합: 최대 16개image[] 필드를 반복하십시오; 16개를 초과하면 오류가 발생합니다
📎 다중 이미지 융합에서는 순서가 중요합니다image[] 필드는 여러 참조 이미지를 허용합니다. 업로드 순서는 프롬프트의 “image 1 / image 2 / image 3” 참조에 매핑됩니다. 명시적으로 참조하십시오:
image 1의 주제를 image 2의 장면에 배치하고, image 3의 색상 스타일을 사용하십시오
파일당 제한: 각각 50MB 미만(multipart 파일 업로드), 형식: png / jpg / webp; 실제로는 업로드 전에 1.5MB 이내로 압축하는 것이 좋습니다(아래의 “업로드 크기 제한” 참조).

코드 예시

Python (OpenAI SDK · 단일 이미지 편집)

Python (OpenAI SDK · 다중 이미지 융합)

cURL (다중 이미지 융합)

cURL (마스크 인페인팅)

Node.js (네이티브 fetch + FormData · 다중 이미지 융합)

매개변수 참고

레거시 DALL·E 값 standard / hdquality에 전달하지 마십시오. 공식 열거형 값 low / medium / high / auto 네 개만 허용됩니다. 레거시 값은 백엔드 채널마다 동작이 일관되지 않습니다. 어떤 경우에는 400(invalid_value)으로 즉시 실패하고, 어떤 경우에는 조용히 무시되어 요청이 auto로 실행됩니다(비용을 예측할 수 없음). 항상 네 가지 공식 값 중 하나를 명시적으로 전달하십시오.

업로드 크기 제한

전체 요청 크기를 최대치까지 채우지 마십시오: 이미지당 상한이 50MB이고 최대 16개 이미지를 보낼 수 있더라도, 상한에 가까운 이미지가 여러 개 있으면 단일 요청 본문이 지나치게 커져 게이트웨이 / CDN / 타임아웃 실패가 발생하기 쉽습니다. 실제로는 각 이미지를 1.5MB 이내로 압축(JPEG 품질 80-90)하면 성공률과 생성 속도 모두 눈에 띄게 좋아지며, 출력 품질은 입력 파일 크기와 무관합니다.

참조 이미지 형식 요구사항 및 전처리

/v1/images/editspng / jpg / webp 표준 형식만 허용합니다. 다음과 같은 400 오류를 받는 경우:
참조 이미지는 대부분 표준 JPEG/PNG가 아닙니다. 가장 흔한 함정은 휴대폰 카메라의 MPO 형식(Multi-Picture Object, 다중 프레임 JPEG 컨테이너)입니다. .jpg Huawei Mate 시리즈 휴대폰에서 바로 나온 파일은 HDR gain-map 하위 프레임을 포함하며 실제로는 MPO입니다. 이러한 파일은 동일한 FFD8 헤더로 시작합니다. 즉, 확장자와 file 명령 모두 JPEG라고 보고하므로 육안으로는 구분할 수 없습니다. 프레임을 인식하는 파싱(예: Pillow)만 이를 판별할 수 있습니다. 오류의 “image 1”은 N번째 참조 이미지(1부터 시작하는 인덱스)를 의미하므로, 인덱스를 사용해 문제 파일을 찾으십시오.
2026년 7월 검증 완료: MPO 파일은 5/5 업로드에서 모두 400 오류로 실패했으며, 같은 이미지를 표준 JPEG/PNG로 다시 인코딩하자 원래의 3072×4096 해상도 그대로 성공했습니다. 문제는 크기나 파일 크기가 아니라 형식입니다. 오류는 입력 검증 단계에서 빠르게(약 4초) 반환되며 과금되지 않습니다.
탐지 및 수정: Image.open(f).format"MPO"을 반환하면 파일을 변환해야 합니다. 업로드 파이프라인에 한 번의 재인코딩 단계를 넣으면 HEIC 및 기타 휴대폰 형식도 함께 처리할 수 있습니다.
제품이 사용자가 촬영한 사진(실내 렌더링, 제품 사진 등)을 허용한다면, 이미지를 하나씩 디버깅하기보다 서버 측에서 일관되게 재인코딩하는 편이 좋습니다. 휴대폰 HDR 사진은 계속 들어올 수 있기 때문입니다. 추가 입력 처리 팁: Image API Essentials and Best Practices.

마스크 인페인팅 요구사항

  • 원본과 동일한 크기여야 하며, PNG 형식이고, 4MB 미만이어야 합니다.
  • 알파 채널이 있어야 합니다: 투명(알파=0) = 인페인트 영역, 불투명 = 유지
  • 마스크는 첫 번째 이미지에만 적용됩니다
  • 마스크는 “부드러운 가이드”입니다 — 모델이 마스크된 영역 주변을 확장하거나 축소할 수 있습니다
멀티턴 반복: 이전 출력을 다음 호출의 image[]로 다시 전달하고, 점진적으로 정교화하는 새 지시를 추가합니다. 각 라운드는 독립적으로 token 기준 과금됩니다 — 누적 비용을 주의하십시오.

Response Format

b64_json is raw base64, without the data:image/...;base64, prefix — different from gpt-image-2-all. Decode it client-side to write a file, or prepend the prefix for browser rendering.
Edit requests’ input_tokens are typically significantly higher than text-to-image at the same size, because reference images are billed per Vision pricing rules — the exact amount is available directly in usage.input_tokens_details.image_tokens, tracked separately from the text portion (text_tokens). Multi-image fusion increases image_tokens strictly linearly per additional reference image (verified July 2026: 4 × 1024² images = 4 × 1024 tokens) — see How Multiple Input Images Affect the Price for the measurement table. See How to check the real token count for each call on the overview page for the full field reference.

인증

Authorization
string
header
필수

API Key obtained from APIYI Console

본문

multipart/form-data
model
enum<string>
기본값:gpt-image-2
필수

Model name, fixed as gpt-image-2

사용 가능한 옵션:
gpt-image-2
prompt
string
필수

Edit/fusion instruction. For multi-image, use 'image 1 / image 2 / image 3' to reference upload order

예시:

"Place subject from image 1 into scene from image 2, using color style from image 3"

image
file[]
필수

Reference images. For a single image, send the field once; for multiple images, repeat the same image field (e.g., -F [email protected] -F [email protected], max 16) — upload order maps to image 1 / image 2 / ... in the prompt. multipart file upload: each under 50MB, formats: png/jpg/webp; compress to within 1.5MB in practice

mask
file

Mask image (optional, only applies to first image). Requirements:

  • Same size as original
  • PNG format, under 4MB
  • Must have alpha channel (alpha=0 = inpaint area, opaque = preserve)
size
string
기본값:auto

Output size (same as text-to-image). Preset or constraint-satisfying custom size

예시:

"1536x1024"

quality
enum<string>
기본값:auto

Quality tier

사용 가능한 옵션:
auto,
low,
medium,
high
output_format
enum<string>
기본값:png

Output format

사용 가능한 옵션:
png,
jpeg,
webp
output_compression
integer

Output compression (0–100), only effective for jpeg/webp

필수 범위: 0 <= x <= 100
background
enum<string>
기본값:auto

Background mode. auto or opaque. Not supported: transparent

사용 가능한 옵션:
auto,
opaque

응답

Image generated successfully

created
integer
예시:

1776832476

data
object[]

Generation results (this model returns 1 image per call)

usage
object

Token usage for this call