많은 개발자가 gpt-image-2의 이미지 편집 인터페이스를 연동할 때 공통적으로 겪는 문제가 있습니다. images/edit API 레퍼런스 페이지를 샅샅이 뒤져봐도 "GPT image 모델은 최대 16장의 이미지를 전송할 수 있다"는 문구만 보일 뿐, 정작 중요한 단일 이미지 용량 제한은 찾을 수 없기 때문이죠. 제한이 없는 걸까요, 아니면 문서가 누락된 걸까요?
정답은 제한이 존재하며 매우 명확하다는 것입니다. 단일 이미지는 반드시 50MB 미만이어야 하며, PNG, WebP, JPG 세 가지 형식만 지원합니다. 다만 이 규칙이 레퍼런스 페이지의 파라미터 표가 아닌, 별도의 '이미지 생성(Image Generation) 사용 가이드' 문서에 기재되어 있어 많은 분이 혼란을 겪곤 합니다.
이번 글에서는 gpt-image-2 API의 이미지 업로드 제한 사항을 수량, 용량, 형식, 마스크(mask) 규칙, 해상도 제약까지 한 번에 정리해 드립니다. 또한, 50MB라는 상한선보다 더 중요한 실전 문제, 즉 "왜 50MB에 꽉 채워 이미지를 전송하면 안 되는지"에 대해서도 다뤄보겠습니다.
gpt-image-2 API 이미지 업로드 제한: 공식 사양 완벽 정리
결론부터 말씀드리겠습니다. gpt-image-2는 v1/images/edits 엔드포인트를 통해 입력 이미지를 받으며, 공식 제한 사항은 아래 표와 같습니다.
gpt-image-2 이미지 업로드 제한 요약표
| 제한 항목 | 공식 사양 | 문서 출처 |
|---|---|---|
| 1회 최대 이미지 수 | 16장 (GPT image 시리즈 모델) | API Reference: images/edit |
| 단일 이미지 용량 | 50MB 미만 | 이미지 생성 사용 가이드 |
| 지원 형식 | PNG, WebP, JPG | 이미지 생성 사용 가이드 |
| 전송 방식 | image_url 또는 file_id 중 택 1 |
API Reference: images/edit |
| 마스크(mask) | 원본과 동일 형식/크기, 50MB 미만, 알파 채널 필수 | 이미지 생성 사용 가이드 |
| 1회 생성 수량(n) | 1~10장 | API Reference: images/edit |
즉, 이론적으로는 한 번의 edit 요청에 50MB에 가까운 이미지 16장을 담아 보낼 수 있습니다. 하지만 "이론적 상한선"과 "실제 엔지니어링에서의 활용"은 별개의 문제이며, 이에 대해서는 뒤에서 자세히 다루겠습니다.
여기서 주의해야 할 점이 하나 있습니다. 새 버전 API의 images 파라미터는 객체 배열을 받으며, 각 객체는 image_url 또는 file_id 중 하나를 제공해야 합니다. file_id는 Files API를 통해 미리 업로드한 파일로, 재사용이 잦은 소재 라이브러리 구성에 적합합니다. image_url은 공용 인터넷 주소나 base64 데이터 URL을 지원하며, 일회성 요청에 적합합니다. 두 방식 모두 50MB 제한은 동일하게 적용됩니다.
🎯 빠른 검증 팁: 이미지가 제한에 걸릴지 확실하지 않다면, 실제 요청을 보내 에러 메시지를 확인하는 것이 가장 빠릅니다. APIYI(apiyi.com)의 OpenAI 호환 인터페이스를 통해 이러한 경계 테스트를 진행해 보세요. 플랫폼의 로그 패널에서 요청 본문 크기와 에러 상세 내용을 한눈에 볼 수 있어, 공식 API를 직접 호출하는 것보다 문제 해결이 훨씬 직관적입니다.
gpt-image-2 업로드 크기가 문서에서 "보이지 않는" 이유
처음 가졌던 의문으로 돌아가 봅시다. 왜 Reference 페이지에는 16장이라는 개수만 적혀 있고 파일 크기는 없을까요? 이는 OpenAI 문서 구조의 설계상 선택 때문입니다. images/edit의 Reference 페이지는 "파라미터 스키마(Parameter Schema)"를 기준으로 구성되어 있습니다. images 파라미터는 스키마 레벨에서 객체 배열일 뿐이라 개수 제한은 배열 제약 조건으로 포함되었지만, 파일 크기나 형식은 "런타임 검증" 사항이라 이미지 생성 가이드의 서술형 텍스트로 분류되었기 때문입니다.
이처럼 "가이드 속에 숨겨진" 규칙이 몇 가지 더 있습니다. 이미지 편집 기능을 구현하기 전에 꼭 함께 확인해 보세요.
- mask(마스크)의 3가지 요구 사항: 편집할 이미지와 동일한 형식, 동일한 크기여야 하며, 파일 크기 역시 50MB 미만이어야 합니다. 또한 반드시 알파 채널을 포함해야 합니다. JPG를 마스크로 사용했다가 오류가 발생하는 경우가 가장 많은데, JPG는 알파 채널을 지원하지 않기 때문입니다.
- 해상도는 자유롭지 않음: gpt-image-2의
size파라미터는 사용자 지정 해상도를 지원하지만, 엄격한 제약이 있습니다. 긴 쪽 변은 3840px를 넘을 수 없고, 가로와 세로 모두 16px의 배수여야 하며, 가로세로 비율은 3:1 이내, 총 픽셀 수는 655,360에서 8,294,400 사이여야 합니다. - 입력 이미지도 과금 대상: edit 요청 시 포함된 참조 이미지는 이미지 입력 토큰으로 계산됩니다.
input_fidelity: high설정 시 소비되는 입력 토큰이 크게 증가합니다.
gpt-image-2 해상도 및 size 파라미터 제약
| 제약 항목 | 규칙 | 예시 |
|---|---|---|
| 긴 쪽 변 | ≤ 3840px | 3840×2160 (4K 가로형) 사용 가능 |
| 변 길이 정렬 | 가로/세로 모두 16px 배수 | 1024, 1536, 2048 모두 적합 |
| 가로세로 비율 | ≤ 3:1 | 2048×1152 적합, 3072×1024 적합 |
| 총 픽셀 수 | 655,360 – 8,294,400 | 768×854 미만은 거부됨 |
| 자주 쓰는 규격 | 1024×1024 / 1536×1024 / 2048×2048 / 3840×2160 | 세로형도 동일하게 적용 |
비즈니스 특성상 다양한 해상도를 자주 전환해야 한다면, 요청을 보내기 전 클라이언트 측에서 로컬 검증을 거쳐 부적합한 크기를 미리 차단하는 것을 권장합니다. API 응답으로 400 오류를 기다리는 것보다 네트워크 왕복을 한 번 줄일 수 있습니다. APIYI(apiyi.com) 문서 센터에도 gpt-image-2 파라미터 검증 목록이 정리되어 있으니, 이를 참고하여 구현해 보세요.
gpt-image-2 실전: 50MB는 상한선, 1.5MB가 정답
50MB라는 하드웨어적 상한선을 알았다면, 실제 엔지니어링 환경에서는 어느 정도 크기의 이미지를 전달해야 할까요? 저희는 이미지당 1.5MB 내외, 최대 5MB를 넘지 않는 것을 권장합니다. 이는 단순히 감으로 정한 것이 아니라, 세 가지 이유가 있습니다.
첫째, base64 인코딩으로 인한 용량 팽창입니다. data URL 방식으로 이미지를 내장하면 base64 인코딩으로 인해 용량이 약 33% 증가합니다. 40MB 원본 이미지가 인코딩 후 53MB에 육박하게 되어, JSON 구조까지 더해지면 요청 본문 크기 제한을 초과할 수 있습니다. 16장의 이미지를 모두 base64로 내장하면 이 문제가 16배로 커지므로, 대용량 소재는 반드시 file_id를 통한 사전 업로드 방식을 사용해야 합니다.
둘째, 전송 및 디코딩 시간입니다. 5MB를 초과하면 업로드 시간과 서버 측 디코딩 시간이 비선형적으로 증가하며, 네트워크 상태가 불안정할 때 타임아웃으로 인한 재시도가 발생해 전체적인 이미지 생성 속도를 늦추게 됩니다. 1.5MB 정도의 이미지는 일반적인 가정용 광랜 환경에서 1~2초 내에 업로드가 완료되므로, 안정성과 품질 사이의 최적점이라 할 수 있습니다.
셋째, 화질 개선의 효율 체감입니다. gpt-image-2는 입력 이미지를 처리할 때 내부적으로 전처리를 수행합니다. 입력 해상도가 출력 해상도보다 훨씬 높으면, 남는 픽셀은 대부분 낭비됩니다. 긴 쪽 변이 3840px이고 2MB 이내로 압축된 JPG는 40MB짜리 무손실 PNG와 비교했을 때 편집 결과물에서 거의 차이를 느낄 수 없지만, 비용과 시간은 크게 차이가 납니다.
gpt-image-2 이미지 크기 실전 권장 사항
| 원본 상태 | 권장 처리 방식 | 예상 결과 |
|---|---|---|
| < 1.5MB | 직접 업로드 | 최적의 속도와 안정성 |
| 1.5MB – 5MB | 직접 업로드 가능, JPG/WebP 변환 권장 | 수용 가능한 속도 |
| 5MB – 20MB | 긴 쪽 변 ≤ 3840px + 품질 85로 압축 | 화질 손실 거의 없음, 시간 대폭 단축 |
| 20MB – 50MB | 반드시 압축, file_id 업로드 권장 | base64 팽창으로 인한 오류 방지 |
| > 50MB | 상한선 초과, 필수 압축 | 오류 발생 |
💡 대량 처리 팁: 이커머스 누끼 따기, 대량 스타일 변환 등 높은 동시성을 요구하는 작업에서는 업로드 전 sharp나 Pillow 라이브러리를 사용하여 "긴 쪽 변 3840px + JPG 품질 85"로 사전 압축하는 것을 권장합니다. APIYI(apiyi.com)의 기업 고객 사례에서 검증한 결과, 이 단계를 거치면 단일 edit 요청의 엔드투엔드 처리 시간이 평균 40% 이상 단축되며 화질 관련 불만은 제로였습니다.
gpt-image-2 API 빠른 시작: 다중 이미지 편집 코드 예제
gpt-image-2는 표준 OpenAI 인터페이스 프로토콜을 따릅니다. 아래는 여러 장의 참조 이미지를 포함하는 가장 간단한 편집 예제입니다. APIYI를 통해 중계할 경우 base_url만 교체하면 바로 사용할 수 있습니다.
import base64
from openai import OpenAI
client = OpenAI(
api_key="sk-your-apiyi-key",
base_url="https://api.apiyi.com/v1" # APIYI 통합 인터페이스
)
def to_data_url(path):
with open(path, "rb") as f:
b64 = base64.b64encode(f.read()).decode()
return f"data:image/jpeg;base64,{b64}"
result = client.images.edit(
model="gpt-image-2",
image=[to_data_url("product.jpg"), to_data_url("style-ref.jpg")],
prompt="제품 이미지에 참조 이미지의 네온 사이버펑크 스타일을 입히되, 제품 본체는 그대로 유지해줘",
input_fidelity="high", # 입력 디테일을 고충실도로 유지, 입력 토큰 소모량 증가
size="2048x2048",
quality="high"
)
print(result.data[0].b64_json[:64]) # base64로 인코딩된 결과 이미지 반환
몇 가지 핵심 파라미터: input_fidelity를 high로 설정하면 얼굴, 로고 등 세부 정보의 유지력이 크게 향상되지만, 그 대가로 이미지 입력 토큰 비용이 증가합니다. quality와 size는 출력 비용을 결정하는 두 가지 주요 요소입니다. n 파라미터는 한 번에 최대 10장까지 생성 가능합니다. 비용 측면에서 gpt-image-2는 토큰 단위로 과금됩니다. 텍스트 입력 $5/M, 이미지 입력 $8/M(캐시 적중 시 $2/M), 이미지 출력 $30/M입니다. 단일 이미지로 환산하면 1024×1024 기준 low 등급은 약 $0.006, medium 등급은 약 $0.05, high 등급은 약 $0.21이며, 출력 측 비용이 가장 큰 비중을 차지합니다.
또한 공식 속도 제한은 계정 등급에 따라 다릅니다. Tier 1은 분당 5장, Tier 4는 150장, Tier 5는 250장입니다. 신규 계정은 등급이 낮아 대량 작업 시 쉽게 제한에 걸릴 수 있습니다. APIYI(apiyi.com)와 같은 통합 플랫폼을 통해 호출하면 단일 계정의 등급 제한을 우회할 수 있어, 높은 동시성이 필요한 프로덕션 환경에 적합합니다.
gpt-image-2와 이전 세대 모델의 업로드 제한 차이
만약 gpt-image-1이나 DALL·E 2에서 프로젝트를 마이그레이션하는 경우, 몇 가지 세대 간 차이점을 유의해야 합니다. 가장 큰 변화는 DALL·E 2에서 GPT image 시리즈로 넘어오면서 발생했습니다. DALL·E 2의 편집 인터페이스는 정사각형 PNG만 허용하며 4MB 미만이어야 했지만, GPT image 시리즈로 오면서 16장, 50MB, 세 가지 형식으로 완화되었습니다. 많은 기존 프로젝트에 하드코딩된 "PNG + 4MB 압축" 전처리 로직은 마이그레이션 후 크게 간소화할 수 있습니다.
gpt-image-2의 gpt-image-1 대비 업그레이드는 주로 해상도와 비용에서 나타납니다. gpt-image-1은 1024×1024, 1536×1024, 1024×1536 세 가지 고정 출력만 지원했지만, gpt-image-2는 사용자 정의 해상도를 지원하며 최대 3840px 긴 변 기준의 4K 출력이 가능합니다. 가격 면에서도 gpt-image-2의 이미지 입력은 $10/M에서 $8/M로, 출력은 $40/M에서 $30/M로 인하되었으며, $2/M의 캐시 적중 등급이 추가되어 참조 이미지를 반복 사용하는 시나리오에서 비용 절감 효과가 뚜렷합니다.
gpt-image-2와 역대 모델 업로드 제한 비교
| 비교 항목 | DALL·E 2 | gpt-image-1 | gpt-image-2 |
|---|---|---|---|
| 입력 이미지 수 | 1장 | 최대 16장 | 최대 16장 |
| 단일 이미지 크기 상한 | < 4MB | < 50MB | < 50MB |
| 입력 형식 | 정사각형 PNG만 | PNG/WebP/JPG | PNG/WebP/JPG |
| 출력 해상도 | 고정 정사각형 | 3종 고정 사이즈 | 사용자 정의, 긴 변 최대 3840px |
| 이미지 출력 가격 | 장당 과금 | $40/M tokens | $30/M tokens (입력 캐시 $2/M) |
| input_fidelity | 지원 안 함 | 지원 | 지원, 고충실도 디테일 강화 |
코드를 마이그레이션할 때는 기본적으로 model 파라미터만 수정하면 되지만, 앞서 언급한 제약 사항에 맞춰 해상도 검증 및 압축 전략을 업데이트하는 것을 권장합니다. 마이그레이션 효과를 먼저 검증하고 싶다면 APIYI(apiyi.com)에서 동일한 소스를 사용하여 두 세대 모델을 각각 호출해 보고, 편집 품질과 실제 과금 차이를 직접 비교해 보세요.
gpt-image-2 이미지 업로드 FAQ
Q1: gpt-image-2에서 이미지 한 장당 최대 용량은 얼마인가요?
하드 제한은 50MB이며, PNG, WebP, JPG 형식을 지원합니다. 이 제한 사항은 images/edit의 참조(Reference) 매개변수 표가 아닌 OpenAI의 이미지 생성 사용 가이드에 명시되어 있어, 참조 페이지만 봐서는 찾기 어려울 수 있습니다. 실무적으로는 1.5~5MB 사이로 조절하는 것이 가장 쾌적한 경험을 제공합니다.
Q2: 이미지 16장 제한은 어떻게 적용되나요?
images 매개변수는 최대 16개의 이미지 객체를 받을 수 있으며, 각 객체는 image_url 또는 file_id를 통해 이미지를 지정합니다. 모델은 여러 장의 이미지를 결합된 참조 이미지로 활용하므로 "제품 이미지 + 스타일 이미지 + 구도 참조"와 같은 복합적인 편집 시나리오에 적합합니다. 16장은 입력 상한선이며, 출력 개수는 n 매개변수로 제어하며 최대 10장까지 가능합니다.
Q3: 마스크(mask) 사용 시 "invalid mask" 오류가 발생하는 이유는 무엇인가요?
대부분 알파 채널 문제일 확률이 90%입니다. 마스크는 편집할 이미지와 동일한 형식 및 크기여야 하며, 반드시 알파 채널을 포함해야 합니다. JPG는 알파 채널을 지원하지 않으므로 마스크는 반드시 PNG를 사용해야 합니다. 투명한 영역은 "재생성 허용"을, 불투명한 영역은 "원본 유지"를 의미합니다.
Q4: base64 업로드와 file_id 업로드 중 무엇을 선택해야 할까요?
작은 이미지(< 5MB)나 일회성 요청에는 base64 데이터 URL이 가장 간편합니다. 반면, 큰 이미지나 여러 번 재사용해야 하는 소스는 Files API를 통해 미리 업로드하여 file_id를 받는 것이 좋습니다. 이는 base64 인코딩 시 발생하는 33%의 용량 증가를 피할 수 있고, 요청 간 재사용도 가능하기 때문입니다. 확실하지 않다면 APIYI(apiyi.com) 콘솔에서 두 방식을 각각 테스트해 보고 실제 소요 시간을 비교한 뒤 결정하세요.
요약: gpt-image-2 업로드 제한의 핵심 숫자 3가지
처음 질문으로 돌아가서, gpt-image-2 이미지 편집 API의 업로드 제한을 세 가지 숫자로 요약할 수 있습니다. 16장(참조 문서에 명시된 단일 입력 이미지 최대 개수), 50MB(사용 가이드에 명시된 이미지당 최대 용량), 1.5MB(실무에서 권장하는 최적의 용량)입니다. 문서에서 개수와 용량 제한이 서로 다른 페이지에 나뉘어 있어 "16장 제한"만 보고 혼동하는 경우가 많습니다.
실무 적용 팁은 간단합니다. 업로드 전 긴 변 기준 3840px 이내, JPG 품질 85 정도로 통일하여 압축하세요. 마스크는 항상 알파 채널이 있는 PNG를 사용하고, 대용량 소스는 file_id 방식을 사용하세요. 이 세 가지만 요청 전 사전 처리 과정으로 고정해도 업로드 관련 오류의 대부분을 방지할 수 있습니다.
국내에서 gpt-image-2를 안정적으로 호출하고 싶거나, 생산 수준으로 속도 제한을 높이고 싶다면 APIYI(apiyi.com)의 통합 인터페이스를 통해 접속해 보세요. OpenAI SDK의 원본 작성 방식을 그대로 지원하며, base_url 한 줄만 변경하면 바로 마이그레이션이 가능합니다.
참고 자료: OpenAI API Reference: developers.openai.com/api/reference/resources/images/methods/edit
작성자: APIYI Team
AI 대규모 언어 모델 API 통합 및 모범 사례 전문. 더 많은 모델 평가 및 연동 가이드는 APIYI(apiyi.com)에서 확인하세요.
