> ## Documentation Index > Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt > Use this file to discover all available pages before exploring further. # GPT-Image-2 이미지 생성/편집 > OpenAI의 플래그십 이미지 생성 모델 gpt-image-2입니다. 2K/4K 해상도를 기본 지원하며, 고충실도 참조 이미지를 자동으로 사용하고, 동일 티어에서 20~30% 더 저렴합니다. 텍스트-이미지, 참조 편집, 다중 이미지 융합, 마스크 인페인팅을 지원합니다. 모든 이미지 API는 **동기식**입니다 — 폴링할 task ID가 없으며, 클라이언트 연결이 끊기면 요청은 계속 과금되는 상태에서 결과가 유실됩니다. 이 모델에는 넉넉한 timeout을 설정하십시오. [이미지 API 필수 사항 및 모범 사례](/ko/api-capabilities/image-api-best-practices)를 참조하십시오. ## 개요 **gpt-image-2**는 OpenAI의 최신 플래그십 이미지 생성 모델로 — `gpt-image-1.5`의 업그레이드 버전입니다. 핵심 업그레이드: **유효한 모든 해상도(2K / 3840×2160 4K 포함)**, **참조 이미지에서 자동 고충실도 적용**, **같은 티어에서 20-30% 더 저렴함**. APIYI의 게이트웨이는 OpenAI Images API와 완전히 호환되므로 — 무코드 직접 연결을 위해 공식 OpenAI SDK의 `base_url`을 여기로 지정하면 됩니다. **🎨 주요 하이라이트**: 유효한 모든 해상도(최대 3840×2160 4K) 기본 지원 + 참조 이미지 편집 시 자동 고충실도 + 동일한 크기와 품질 기준으로 1.5보다 20-30% 저렴 + 중국어 prompt 기본 지원. **정확한 크기/품질 제어가 필요하거나, OpenAI 공식 API와 완전히 일치해야 하거나, 4K 출력을 요구하는 프로덕션 시나리오에 가장 적합합니다**. `/v1/images/generations` — size / quality / output\_format 제어로 텍스트 prompt에서 이미지를 생성합니다. `/v1/images/edits` — 참조 이미지 최대 16장을 multipart 업로드하고 편집/융합 지시를 적용하며, mask 인페인팅을 지원합니다. ## APIYI의 GPT-image-2 공식 릴레이를 선택해야 하는 이유? OpenAI의 공식 채널을 기반으로 하며, **신뢰성**, **비용**, **통합 경험** 측면에서 엔터프라이즈 프로덕션 워크로드에 맞게 깊게 최적화되어 있습니다: OpenAI의 공식 릴레이를 통해 엄격하게 라우팅됩니다 — 요청과 응답은 **OpenAI 공식과 100% 동일**합니다: 필드도 같고, 오류 코드도 같고, 모델 동작도 같습니다. 무손실 품질이며, 몰래 재작성하지 않습니다. OpenAI의 **Tier 기반 RPM / TPM 상한**에 묶이지 않습니다. 엔터프라이즈 규모 트래픽도 선형적으로 확장되며 — 배치 생성과 피크 부하 시나리오를 손쉽게 처리합니다. 기본 단가가 OpenAI의 공식 가격과 일치합니다. [충전 보너스 이벤트](/ko/faq/recharge-promotions)와 함께 사용하면 **최대 15% 할인**을 받을 수 있어 — 장기 비용이 눈에 띄게 낮아집니다. **해외 서버나 프록시가 필요하지 않습니다**. 국내 데이터 센터, 가정용 광대역, 해외 노드에서 `api.apiyi.com`에 직접 연결할 수 있습니다 — 지연 시간이 안정적이며, 국경 간 재설계가 필요 없습니다. 리버스 엔지니어링한 [`gpt-image-2-all`](/ko/api-capabilities/gpt-image-2-all/overview) (\$0.03/image 정액)으로 매끄럽게 전환하거나, 비용 경쟁력이 뛰어난 [Nano Banana Pro / 2](/ko/api-capabilities/nano-banana-2-image/overview)를 사용할 수 있습니다 — 시나리오별로 자유롭게 조합하십시오. 저희 팀은 프로덕션 이미지 생성 배포를 전문으로 하며, 모델 선택, 튜닝, 통합에 대한 깊은 경험을 보유하고 있습니다 — PoC부터 프로덕션까지 엔드투엔드 지원을 제공합니다. ## 핵심 기능 유효한 모든 출력 크기를 지원합니다. 프리셋은 1K / 2K / 3840×2160 4K를 포함합니다. 사용자 지정 크기는 기본 제약만 만족하면 됩니다(가로세로가 16의 배수이고, 비율이 3:1 이하). 참고 이미지 편집 시 자동으로 고충실도가 활성화됩니다. 디테일, 인물 동일성, 텍스트 보존이 크게 향상됩니다. **절대** `input_fidelity`를 전달하지 마십시오(오류가 발생합니다). 1024×1024 고품질은 1.5의 \$0.25대에서 \$0.211/이미지로 내려갑니다. 2K/4K는 token 기준 과금이지만 같은 추세로 낮아지며, 장기 비용이 눈에 띄게 낮습니다. 중국어 prompt를 네이티브로 지원합니다. 간판, 포스터, UI 스크린샷에서 중국어/영문 텍스트를 안정적으로 렌더링합니다. 작은 텍스트도 `high` 품질에서는 흐릿해지는 경우가 드뭅니다. `image[]` 배열은 최대 16개의 참고 이미지를 허용합니다. prompt에서 "image 1 / image 2 / image 3"를 사용해 업로드 순서대로 참조할 수 있습니다. 알파 채널 마스크를 업로드합니다. 투명한 영역은 inpaint 영역이고, 불투명한 영역은 보존됩니다. png(기본값) / jpeg / webp를 지원합니다. 파일 크기를 제어하려면 jpeg/webp에 `output_compression`를 설정하십시오. `base_url`를 `https://api.apiyi.com/v1`로 지정하고 공식 OpenAI SDK로 바로 호출하십시오. 코드 변경 없이 마이그레이션할 수 있습니다. ## 요금 APIYI의 `gpt-image-2` (기본 그룹) **는 OpenAI의 공식 정가와 정확히 동일합니다** — 할인은 대신 충전 보너스에서 제공됩니다: **\$100을 충전하면 10% 보너스를 받고, 최대 20%까지 제공됩니다**. 📖 [충전 프로모션 알아보기](/ko/faq/recharge-promotions). ### 토큰 요율(OpenAI의 목록과 동일) 토큰 기준 과금 — 요청 1건 = 입력 텍스트 + 입력 이미지 + 출력 이미지 token: | 청구 항목 | 가격(1M tokens당) | 참고 | | ------ | ----------------------- | --------------------------------------------------------- | | 텍스트 입력 | \$5.00 | prompt의 텍스트 부분 | | 이미지 입력 | \$8.00 | 편집/융합 요청의 참고 이미지로, Vision 규칙에 따라 token화됩니다 | | 이미지 출력 | \$30.00 | **가장 큰 비용 요인** — 크기 × 품질에 따라 token 수가 결정됩니다 | | 캐시된 입력 | 텍스트 \$1.25 / 이미지 \$2.00 | 설정할 수는 있지만, 동시 실행 수가 높으면 적중률이 제한됩니다 — [FAQ](#faq)를 참조하십시오 | **왜 이미지 입력이 더 비쌉니까?** 이미지 입력은 \$8.00 / 1M tokens로, 텍스트 입력 요율 \$5.00 / 1M보다 **1.6배** 비쌉니다(이는 OpenAI의 자체 공개 가격이며, APIYI의 추가 마진이 아닙니다). 이것이 편집 / 다중 이미지 융합 요청이 일반적인 텍스트-이미지 생성보다 입력 측 비용이 눈에 띄게 더 높은 이유이기도 합니다. 참고 이미지는 Vision 규칙에 따라 많은 수의 이미지 token으로 token화되며, 각 token은 이미 텍스트 token보다 60% 더 높은 가격으로 책정되어 있습니다. ### 이미지당 비용 참고(공식 표) 1K 프리셋 크기에서의 일반적인 이미지당 비용입니다: | 품질 | 1024×1024 | 1024×1536 | 1536×1024 | | -- | --------- | --------- | --------- | | 낮음 | \$0.006 | \$0.005 | \$0.005 | | 중간 | \$0.053 | \$0.041 | \$0.041 | | 높음 | \$0.211 | \$0.165 | \$0.165 | **가격 참고 사항**: * 단가표는 OpenAI의 목록 가격과 일치합니다. [충전 보너스](/ko/faq/recharge-promotions)(\$100에 10%, 최대 20%)를 더하면 실효 비용은 직접 이용할 때보다 더 낮아집니다 * 2K / 4K는 이미지당 고정 가격이 없으며, 실제 입력 + 출력 tokens 기준으로 과금됩니다 * 편집 요청은 고정밀이 강제되므로 텍스트-투-이미지보다 입력 tokens가 눈에 띄게 더 높습니다 * 스트리밍(`stream: true` + `partial_images: N`)은 각 부분 출력마다 추가로 100개의 출력 이미지 tokens가 더 듭니다 * 같은 크기와 품질에서 `gpt-image-1.5`와 비교하면, `gpt-image-2`가 약 20-30% 더 저렴합니다 ### 여러 입력 이미지가 가격에 미치는 영향(2026년 7월 검증됨) 많은 고객이 묻는 질문입니다. "참조 이미지마다 정액 요금이 적용되나요, 아니면 더 큰 이미지일수록 더 많은 tokens가 드나요?" 답은 **둘 다 영향을 미치며, 이미지 수는 엄격하게 선형적으로 누적됩니다**. `gpt-image-2`는 모든 입력 이미지를 강제 고해상도로 처리하며(`input_fidelity`는 조정할 수 없습니다. 이를 전달하면 400이 반환됩니다), 각 참조 이미지는 크기와 종횡비에 따라 image token으로 변환됩니다. 통제된 측정값(편집 endpoint, 2026-07-15): | 참조 이미지 입력 | `image_tokens` | 입력 비용 (\$8/M) | | ------------------- | --------------------- | ------------- | | 1 × 512×512 | 1024 | ≈\$0.0082 | | 1 × 1024×1024 | 1024 | ≈\$0.0082 | | 1 × 2048×2048 | 1521 | ≈\$0.0122 | | 1 × 4096×4096 | 1521 | ≈\$0.0122 | | 1 × 1024×1536 (세로형) | 1536 | ≈\$0.0123 | | **4 × 1024×1024** | **4096 (= 4 × 1024)** | ≈\$0.0328 | 세 가지 경험칙입니다. 1. **개수는 엄격하게 선형입니다**: N개의 참조 이미지는 대략 N × 단일 이미지 tokens입니다. 1024² 해상도의 참조 이미지 16장은 ≈ 16384 tokens ≈ \$0.13으로, 하나의 `high` 출력(\$0.211)과 같은 자릿수이므로 여러 이미지 융합에서는 더 이상 무시할 수 없습니다. 2. **크기에는 하한과 상한이 모두 있습니다**: 1024² 이하의 정사각형 이미지는 모두 1024 tokens로 과금됩니다(512로 줄여도 **절약되는 것은 없습니다**). 2048²와 4096²는 모두 1521 tokens가 듭니다(과도하게 큰 이미지는 변환 전에 축소되므로 **상한이 적용됩니다**). 단일 참조 이미지는 종횡비를 포함해 대략 800\~1600 token 범위에 들어갑니다. 3. **tokens는 파일 크기가 아니라 픽셀 크기로 결정됩니다**: 1.5MB로 압축하면 업로드 안정성과 속도는 좋아지지만 **image tokens는 줄지 않습니다**. 반대로 50MB 원본을 올려도 요금이 폭증하지는 않습니다(상한이 적용됩니다). 비용 감각: `low` 출력(196 tokens ≈ \$0.006)에서는 참조 이미지 1장의 입력 비용(≈\$0.008)이 실제로 출력보다 더 큽니다. `high` 출력(≈\$0.211)에서는 참조 이미지 1장이 약 4%에 불과합니다. **출력 크기와 품질이 언제나 가장 큰 가격 레버입니다** — 참조 이미지 수는 그다음입니다. ### 2K/4K 비용 추정치(픽셀 비율 외삽, ⚠️ 공식 고정 가격 아님) OpenAI는 1K 크기에 대해서만 이미지당 고정 가격표를 공개합니다 — **2K/4K에 대한 공식적인 크기별 가격은 없습니다**. 아래 표는 위의 1K 공식 요율을 기준으로 픽셀 수에 따라 스케일링한 APIYI의 자체 외삽이며, 예산 산정용일 뿐입니다: | 품질 | 2048×2048 (2K 정사각형) | 2048×1152 (2K 가로형) | 3840×2160 / 2160×3840 (4K) | | -- | ------------------- | ------------------ | -------------------------- | | 낮음 | ≈\$0.024 | ≈\$0.008 | ≈\$0.026 | | 중간 | ≈\$0.212 | ≈\$0.062 | ≈\$0.216 | | 높음 | ≈\$0.844 | ≈\$0.248 | ≈\$0.870 | **이것은 추정치이며, 공식 가격표가 아닙니다.** 방법: 같은 종횡비의 1K 공식 행을 기준선으로 사용한 뒤, 목표 크기의 픽셀 수를 해당 기준선 대비 비율로 선형 스케일링합니다(예: 2048×2048은 1024×1024보다 픽셀이 4배이므로 추정 비용도 ×4입니다). 실제 출력 image token 수는 콘텐츠 복잡도에 따라 모델이 동적으로 결정하며, 엄밀히 선형적이지는 않으므로 **실제 응답의 `usage.output_tokens`을 기준으로 삼으십시오**(아래의 "각 호출의 실제 token 수를 확인하는 방법" 참조). `high` 품질에서 2560×1440을 초과하는 크기는 여전히 공식 실험 단계이므로, 그 구간의 추정치는 정확도가 떨어질 수 있습니다. ### SaaS 구독 / 크레딧 기반 과금과의 차이 이미지 생성 도구 제공업체는 일반적으로 두 가지 방식으로 과금합니다. * **월간 구독 요금제**: 월 정액으로 “월 N개 이미지” 쿼터를 제공하는 방식입니다. 이 쿼터는 **과대 판매 가정**을 바탕으로 가격이 책정됩니다. 즉, 제공업체는 대부분의 사용자가 할당량을 모두 사용하지 않을 것이라는 기대를 가격에 반영하므로, 광고되는 “이미지당 비용”은 실제로 개별 이미지를 생성하는 데 드는 비용이 아니라 요금제 가격을 쿼터 상한으로 나눈 값에 불과합니다. * **크레딧 / 포인트 기반 계량**: 품질이나 크기가 다른 작업을 불투명한 “크레딧”으로 환산합니다. 이는 사실상 내부적으로는 사용량 기반 과금이지만, 실제 token 소비를 가리는 크레딧 단위 뒤에 다시 포장한 것에 불과합니다. APIYI는 **공식 릴레이 + 실제 token 계량 과금** 모델로 운영됩니다. 요금제 쿼터도 없고, 크레딧 추상화 계층도 없습니다. 각 호출의 비용은 단순히 실제 입력/출력 token × 공식 요율이며, 구독의 과대 판매나 한도를 초과했을 때의 차단 동작 없이 호출 단위로 정확하게 계산됩니다. 사용량 기반 과금의 트레이드오프는 구독처럼 월 고정 총액의 확실성을 얻는 대신 사용량을 직접 추정하고 모니터링해야 한다는 점입니다. 장점은 실제로 사용한 만큼만 지불하므로 유휴 낭비가 없다는 것입니다. 아래 방법을 사용하면 응답에서 각 호출의 실제 token 수를 바로 추출하여 직접 정산할 수 있습니다. ### 각 호출의 실제 token 수를 확인하는 방법 `/v1/images/generations`와 `/v1/images/edits` 모두 `usage` 필드를 반환하며, **image input token과 text input token은 별도 필드로 돌아옵니다** — 추정할 필요 없이 그대로 읽으면 각 호출의 정확한 비용을 알 수 있습니다. 참조 이미지 1개가 포함된 실제 편집 요청에서 캡처한 전체 `usage` 객체는 다음과 같습니다: ```json theme={null} { "data": [ { "b64_json": "..." } ], "usage": { "input_tokens": 848, "input_tokens_details": { "image_tokens": 832, "text_tokens": 16 }, "output_tokens": 196, "output_tokens_details": { "image_tokens": 196, "text_tokens": 0 }, "total_tokens": 1044 } } ``` | 필드 | 의미 | | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `usage.input_tokens_details.text_tokens` | 프롬프트 텍스트에 의해 소모된 token으로, \$5.00 / 1M 요금이 부과됩니다 | | `usage.input_tokens_details.image_tokens` | Vision 규칙에 따라 참조 이미지가 변환되는 token으로, \$8.00 / 1M 요금이 부과됩니다; 참조 이미지가 없는 일반적인 text-to-image에서는 항상 0입니다 | | `usage.input_tokens` | 위 두 필드의 합계입니다 | | `usage.output_tokens` | `quality × size`에 의해 결정되는 생성된 이미지의 token입니다 — 이것이 **가장 큰 비용 요소**이며, \$30.00 / 1M 요금이 부과되고, 2K/4K 요청에서 특히 주의해서 봐야 하는 수치입니다 (`output_tokens_details.image_tokens`이 이를 반영하며; `text_tokens`는 항상 0입니다) | | `usage.total_tokens` | 입력 + 출력 합계입니다 | 셀프서비스 비용 공식(정확): ``` cost ≈ input_tokens_details.text_tokens × \$5.00 / 1,000,000 + input_tokens_details.image_tokens × \$8.00 / 1,000,000 + output_tokens × \$30.00 / 1,000,000 ``` 과거 호출의 실제 token 사용량과 과금 세부 정보를 확인하려면 콘솔의 “Logs” 페이지를 살펴보십시오: 📖 [How to view your call logs](/ko/faq/call-logs) — 로그 상세 보기에서는 text-input / image-input / output 가격이 각 token 수와 함께 표시되며, API의 `usage.input_tokens_details` / `usage.output_tokens_details`와 일치합니다. Responses API의 `image_generation` 도구는 token 수를 같은 방식으로 `usage.input_tokens` / `usage.output_tokens`로 보고합니다 — [Responses tool integration](/ko/api-capabilities/gpt-image-2/responses-image-tool)를 참고하십시오. ## 그룹 설정 `gpt-image-2` 공식 릴레이 채널은 두 개의 그룹을 제공합니다. 대시보드 → **토큰 설정 → 그룹**에서 전환합니다: | Group | Rate | When to use | | ------------------ | ---- | --------------------------------------------------------------------------------- | | `Default` | 1.0x | OpenAI의 리스트 가격과 동일합니다 — 용량이 있을 때의 첫 번째 선택이며, 피크 시간에는 429 / 동시 실행 수 제한이 발생할 수 있습니다 | | `image2Enterprise` | 1.2x | 기본 그룹의 여유가 빡빡할 때 사용하는 안정적인 대체 수단입니다 — 용량 우선 | **왜 1.2x입니까?** 이는 “\$3,000 단일 충전 프로모션에 20% 보너스를 더하면 OpenAI 리스트 가격과 거의 같습니다”에 맞춰 보정되어 있습니다 — APIYI는 이 경로에서 세금 비용을 제외하면 마진을 남기지 않고 순수 공급 우선 채널로 운영합니다. 기본 그룹이 불안정하면 토큰을 `image2Enterprise`으로 전환하여 급등 구간을 버티십시오. 토큰 생성 UI: 과금 모드 = 종량제 우선, 그룹 = image2Enterprise (1.2x), 고속 리스트 가격 GPT-image-2 엔터프라이즈 그룹 📖 안정성 점검(최근 호출 로그): [/en/live/2026-04/image2-enterprise-stable](/en/live/2026-04/image2-enterprise-stable) ## 기술 사양 | Dimension | Value | | -------------- | ------------------------------------------------------------------------------------- | | **모델명** | `gpt-image-2` | | **속도** | 약 120초(4K 고품질은 약 2분에 접근함) | | **출력 해상도** | 유효한 모든 크기(1K/2K/4K, 최대 3840×2160) | | **품질 등급** | `auto` / `low` / `medium` / `high` | | **출력 형식** | `png`(기본값) / `jpeg` / `webp` | | **중국어 프롬프트** | ✅ 네이티브 | | **요청당** | 이미지 1장(`n=1`) | | **참조 이미지 제한** | 16(`image[]`) | | **이미지당 크기 제한** | multipart 파일: 각 50MB 미만(png/jpg/webp); base64 data URL: 필드 제한 약 20MiB, 원본은 15MB 이내 유지 | | **마스크 인페인팅** | ✅ 지원됨(알파 채널 필요, PNG 4MB 미만) | | **투명 배경** | ❌ 지원되지 않음(`background: transparent` 오류) | | **응답 필드** | `b64_json` (**raw base64, 접두사 없음**) | ## 엔드포인트 | Endpoint | 용도 | Content-Type | | ----------------------------- | ---------------------------- | --------------------- | | `POST /v1/images/generations` | 텍스트-투-이미지 | `application/json` | | `POST /v1/images/edits` | 참조 편집 / 다중 이미지 융합 / 마스크 인페인팅 | `multipart/form-data` | **도메인 선택**: `api.apiyi.com`이 기본 도메인입니다. `b.apiyi.com` / `vip.apiyi.com` 같은 다른 게이트웨이 도메인도 동일하게 동작합니다. ## 크기 참조 ### 사전 설정된 크기 | size | 의미 | Pixels | | ----------- | -------- | --------- | | `auto` | 적응형(기본값) | 모델이 결정합니다 | | `1024x1024` | 정사각형 1:1 | 1K | | `1536x1024` | 가로형 3:2 | 1K | | `1024x1536` | 세로형 2:3 | 1K | | `2048x2048` | 정사각형 1:1 | 2K | | `2048x1152` | 가로형 16:9 | 2K | | `3840x2160` | 가로형 16:9 | 4K | | `2160x3840` | 세로형 9:16 | 4K | ### 사용자 지정 크기 제약 `gpt-image-2`은 다음 조건을 모두 만족하는 유효한 크기라면 무엇이든 허용합니다. 1. **최대 변 ≤ 3840px** 2. **양쪽 변이 모두 16의 배수** 3. **가로세로 비율 ≤ 3:1** 4. **총 픽셀 수 ∈ \[655,360, 8,294,400]** (\~0.65MP to \~8.3MP) **유효한 예시**: `1600x1200`, `1792x1024`, `2048x1536`, `3200x1800` **유효하지 않은 예시**: `1000x1000` (16의 배수가 아님), `4000x4000` (최대값 초과), `3840x1000` (비율 > 3:1) `2560×1440`을 초과하는 출력은 (\~3.69MP) 공식적으로 **실험적**으로 표시되며 품질 변동이 있을 수 있습니다. 프로덕션에서는 `2048x1152` / `2048x2048` / `3840x2160` 같은 사전 설정을 사용하는 것이 좋습니다. ## 품질 참조 ### 사용 가능한 티어 | quality | 의미 | 비고 | | -------- | ----------- | --------------------------------------------------- | | `auto` | 자동(**기본값**) | `quality`이 생략될 때 사용되는 값입니다 — 모델이 사용자를 대신해 티어를 선택합니다 | | `low` | 낮은 품질 | 가장 빠르고 가장 저렴합니다 — 초안 / 배치에 적합합니다 | | `medium` | 중간 품질 | 일상 사용 / 최종 출력에 적합한 균형 잡힌 선택입니다 | | `high` | 높은 품질 | 텍스트, 미세 텍스처, 인쇄 — 가장 높은 지연 시간과 비용 | **기본값은 `auto`이지 `medium`이 아닙니다.** `quality`을 생략하는 것은 `"quality": "auto"`을 전달하는 것과 같습니다 — 모델이 품질 티어를 자동 선택하며, **OpenAI는 이것이 `medium`에 매핑된다고 보장하지 않습니다.** `auto`이 결정하는 티어는 예측할 수 없으며 비용, 지연 시간, 과금 안정성에 직접적인 영향을 줍니다. **비용 제어와 예측 가능성이 필요하다면, `low` / `medium` / `high`을 사용하는 대신 `auto`에 의존하지 말고 명시적으로 전달하십시오.** **레거시 DALL·E 값인 `standard` / `hd`은 전달하지 마십시오.** `quality`는 공식 enum 값 네 개인 `low` / `medium` / `high` / `auto`만 허용합니다. 레거시 DALL·E 3 값인 `standard` / `hd`은 백엔드 채널마다 일관되지 않게 동작합니다: 때로는 400(`invalid_value`)으로 즉시 실패하고, 때로는 조용히 무시되어 요청이 `auto`로 실행됩니다(예측할 수 없는 비용). 항상 네 가지 공식 값을 하나 명시적으로 전달하십시오. **`quality`이 가격에 미치는 영향이 가장 큽니다 — `size`보다도 큽니다.** 출력 이미지 token 수는 `quality × size`의 영향을 받지만, `quality`가 훨씬 더 큰 비중을 차지합니다: 같은 크기에서 `low`에서 `high`로 바뀌면 이미지당 비용이 **30배 이상** 달라질 수 있습니다(위의 "per-image cost" 표를 참고하십시오: 1024×1024는 `low` \$0.006에서 `high` \$0.211까지입니다). 먼저 `quality`으로 비용을 추정한 다음, `size`의 영향을 반영하십시오. ## 모범 사례 **온보딩 팁: 먼저 `low`로 API를 동작시키고, 그다음 규모를 키우십시오** 새로운 통합 작업에서 곧바로 `quality=high` + 고해상도로 시작했다가 이미지당 \*\*≈ 235초(\~4분)\*\*를 기다리며 API가 멈춘 것 같다고 의심하는 사례를 보았습니다. `high` 모드는 추론 복잡도가 가장 높으며, 4K는 거의 5분까지 늘어날 수 있습니다. **프로덕션에 투입하기 전에 먼저 `quality=low`로 엔드 투 엔드 통합하십시오**(인증, SDK, 매개변수, 타임아웃, 오류 처리), 그런 다음 실제 품질 요구가 필요로 할 때만 `medium` / `high`으로 올리십시오. 새로운 통합에서는 **`quality=low` + 사전 설정 크기**로 시작하여 전체 호출 체인(인증, 매개변수, 타임아웃, 오류 처리)을 검증하십시오. `low`는 `high`보다 몇 배 더 빠르므로, 긴 지연 시간에 가려지지 않고 기능 문제가 빠르게 드러납니다. 공식 사전 설정 8개는 안정적인 속도와 품질에 맞게 조정되어 있습니다. 정말로 특이한 가로세로 비율이 필요한 경우에만 사용자 지정 크기를 사용하십시오. 초안 / 배치 → `low`; 일상 / 최종 → `medium`; 텍스트, 섬세한 질감, 인쇄 → `high`. **`low` ↔ `high`는 시각적 충실도 이상의 의미가 있으며, 추론 복잡도에서도 단계적 변화가 일어납니다**. 따라서 지연 시간도 그에 맞게 증가합니다. 최종 표시용으로는 `output_format=jpeg` + `output_compression=85`가 PNG보다 더 빠르고 크기도 대략 절반입니다. 텍스트 렌더링은 핵심 강점이지만 낮은 등급에서는 여전히 흐려질 수 있습니다. 간판과 포스터 시나리오에는 `quality=high`로 고정하십시오. 각 이미지는 최대 50MB이며(실제로는 1.5MB 이내로 압축), PNG/JPEG/WebP를 지원하고, 최대 16장까지 사용할 수 있습니다. 프롬프트에서 “이미지 1 / 이미지 2”로 참조 순서를 지정하십시오. 지연 시간을 좌우하는 두 매개변수는 \*\*`quality`\*\*와 \*\*`size`\*\*입니다 — 특히 `quality`입니다. 계층별로 클라이언트 타임아웃을 구성하십시오: | 품질 | 권장 클라이언트 타임아웃 | 관측된 지연 시간 | | -------- | ---------------- | -------------------------------------- | | `low` | ≥ **120초** | 일반적으로 10–40초 | | `medium` | ≥ **240초** | 일반적으로 30–90초 | | `high` | ≥ **600초** (안전망) | 2K/4K는 3\~5분이 걸리며, 235초 이상에서 긴 꼬리가 관찰됨 | **`high` 모드에서는 대기열, 긴 꼬리 변동성, 상위 시스템 지터를 흡수할 수 있도록 600초를 안전망 타임아웃으로 설정하십시오**. UI에서 진행 상황을 표시하고, 서버 측 작업 큐도 고려하십시오. `gpt-image-1.5`에서 마이그레이션하는 경우: `input_fidelity`는 제거하십시오(강제 고충실도이며 전달하면 오류가 발생합니다); `background: transparent`는 사용하지 마십시오(지원되지 않습니다). ## 오류 및 재시도 | 상태 | 의미 | 권장 조치 | | ------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `400` | 잘못된 매개변수(크기 제약 위반, 지원되지 않는 필드 등) | 크기 제약을 확인하고, **`input_fidelity` / `background: transparent`를 전달하지 마십시오**; 편집 엔드포인트의 `invalid_image_file`는 보통 MPO 휴대폰 사진입니다 — [FAQ](#faq)를 참조하십시오 | | `401` | 잘못된 token | Bearer Token을 확인하십시오 | | `403` | 콘텐츠 모더레이션 차단 | prompt를 조정하거나 `moderation: low`를 전달하십시오 | | `429` | 요청 제한 / 잔액 부족 | 지수 백오프 | | `5xx` | 게이트웨이 / 백엔드 오류 | 1–2회 재시도 | | Timeout | 롱테일 | `quality`별로 클라이언트 타임아웃을 단계화합니다: `low` ≥ **120s** / `medium` ≥ **240s** / `high` ≥ **600s** (high + 2K/4K 실행은 3–5분이며; 235초 이상에서 롱테일이 관찰되었습니다) | **클라이언트 권장 사항**: * `quality`별로 요청 타임아웃을 단계화합니다: `low` ≥ **120 seconds** / `medium` ≥ **240 seconds** / **`high` ≥ 600 seconds** (안전 장치입니다 — 3–5분이 관찰되며; 120s/360s 정도로 설정하면 잘못된 타임아웃이 많이 발생합니다) * **먼저 `quality=low`와 통합한 다음**, 실제 품질 요구에 따라 `medium` / `high`로 상향하십시오 * 5xx와 타임아웃에는 지수 백오프를 사용하십시오(재시도 2회를 권장합니다) * 지원 문의를 위해 `x-request-id` 헤더를 기록하십시오 ## 자주 묻는 질문 **예**. `gpt-image-2`는 `gpt-image-2-all`와 달리 **원시 base64 문자열**(접두사 없음)을 반환합니다. 클라이언트 패턴은 두 가지입니다. * **파일 쓰기**: `base64.b64decode(b64_str)` → 디스크에 기록 * **브라우저 렌더링**: `img.src = 'data:image/png;base64,' + b64_str`(접두사를 수동으로 추가) 코드가 1.5 시절의 “이미 접두사가 붙은” 동작을 가정하면 손상된 data URL이 생성됩니다. 이 부분은 명시적으로 처리해야 합니다. `gpt-image-2`는 참조 이미지에 대한 고충실도 처리를 **강제**하며 더 이상 `input_fidelity`을 허용하지 않습니다. 1.5에서 마이그레이션할 때는 이 필드만 제거하면 되며, 대체 항목은 필요하지 않습니다. `gpt-image-2`은 `background: transparent`을 **지원하지 않습니다**(오류가 발생합니다). 우회 방법은 두 가지입니다. * `background`를 `opaque`로 설정(또는 생략)한 뒤, PIL / sharp / 온라인 도구로 직접 투명도를 분리합니다. * 투명도가 정말 필요한 시나리오에서는 임시로 `gpt-image-1.5`로 되돌립니다. 1장입니다(`n=1`). N장의 이미지가 필요하면 N개의 병렬 요청을 보내십시오. 각 요청은 독립적으로 token 기준으로 과금됩니다. 해상도와 품질이 높을수록 더 많은 출력 이미지 token이 필요하므로 자연스럽게 더 오래 걸립니다. 실제 고객 연동에서 \*\*`quality=high` + 고해상도는 이미지당 약 235초(\~4분)\*\*가 걸린 사례가 있었고, `3840×2160` + `high`의 긴 꼬리 구간은 거의 5분까지 늘어날 수 있습니다. 권장 사항은 다음과 같습니다. * 먼저 `quality=low`로 연동하여 호출 경로를 검증한 뒤, 실제 품질 요구에 따라 상향합니다. * 품질별로 클라이언트 타임아웃을 단계화합니다: `low` ≥ **120초** / `medium` ≥ **240초** / **`high` ≥ 600초**(안전망) * UI에 “생성 중” 진행 상태를 표시합니다. * 4K가 필요하지 않다면 1024×1024 / 1536×1024 1K 프리셋을 사용합니다. **설정은 되어 있지만, 비용 예산에 캐시 할인을 반영하지 마십시오.** 공식 캐시된 입력 요율은 텍스트 \$1.25 / 이미지 \$2.00 per 1M tokens이며, APIYI 채널에는 캐싱이 설정되어 있습니다. 요청이 캐시에 적중하면 캐시 요율로 과금됩니다. 솔직한 주의점 하나가 있습니다. 높은 동시 실행 수를 유지하려면 APIYI는 요청을 여러 upstream OpenAI 계정으로 분산합니다(OpenAI Tier-5 계정 하나는 250 RPM만 허용). OpenAI의 prompt cache는 계정 간에 공유되지 않으므로, 높은 동시 실행 수에서는 같은 prefix를 공유하는 요청이 같은 계정에 도착하지 않을 수 있습니다. 즉, **캐시가 아예 적중하지 않을 수 있습니다**. 다행히 영향은 작습니다. 이미지 생성에서 가장 큰 비용은 출력 이미지 token(\$30 / 1M)이며, 캐시 할인은 입력 측에만 적용되므로 이미지당 총액에는 거의 영향을 주지 않습니다. 예산은 **입력 전체 가격** 기준으로 잡고, 캐시 적중은 보너스 절감으로 취급하십시오. `gpt-image-2`가 참조 이미지의 고충실도 처리를 자동으로 활성화하기 때문에, 참조 이미지 자체가 Vision 과금 규칙에 따라 큰 입력 token 수로 변환됩니다. 편집 입력 token은 텍스트-이미지보다 눈에 띄게 더 높으므로, 그에 맞춰 예산을 잡으십시오. **근본 원인: `quality`가 `auto`로 설정되어 있었기 때문입니다(또는 생략됨).** “크기, 해상도, 참조 이미지는 모두 같은데 가격이 오르내린다”는 보고가 있었습니다. 조사해 보니 `size`와 `quality`가 모두 `auto`로 설정되어 있었습니다. **범인은 `quality: auto`입니다**: 자동 모드에서는 모델이 요청을 해석하고, 생성할 때마다 다른 품질 티어를 즉석에서 선택합니다. 티어가 다르면 출력 이미지 token 수가 달라지고, 그만큼 가격도 달라집니다. 아래는 입력이 완전히 동일한(각각 1061 input tokens) 실제 과금 항목 3개이지만, 비용은 몇 배씩 차이납니다. | 지연 시간 | 입력 token | 출력 token | 호출당 비용 | | ----- | -------- | -------- | -------------- | | 53초 | 1061 | 1286 | \$0.055082 | | 135초 | 1061 | **5146** | **\$0.194042** | | 68초 | 1061 | 1287 | \$0.055118 | 두 번째 호출에서는 `auto`가 더 높은 품질 티어로 해석되어 출력 token이 5146으로 급증했고, 가격도 약 3.5배 올랐습니다. **해결책: `quality`를 `auto`로 두지 말고 `low` / `medium` / `high`를 명시적으로 전달하십시오.** 고정된 티어를 사용하면 동일한 입력에 대한 출력 token 수와 가격이 안정적이고 예측 가능해집니다. 위의 “품질 참조” 섹션을 참조하십시오. `gpt-image-2` 이미지 편집 엔드포인트(`/v1/images/edits`)는 최대 **16**장의 참조 이미지를 지원합니다. * **multipart/form-data 파일 업로드**: 각 이미지는 **50MB 미만**이어야 하며, 형식은 `png` / `jpg` / `webp`입니다. * **base64 data URL**: 필드 길이 제한은 약 **20MiB**입니다(schema `maxLength: 20971520` — 문자열 필드 제한이며, 50MB multipart 상한과는 **동일하지 않습니다**). 따라서 원본 이미지는 **15MB 이내**로 유지하십시오. * **마스크 파일**: 별도로 **PNG 4MB 미만**으로 제한됩니다. 실용적인 조언: 큰 이미지를 여러 장 한꺼번에 최대치로 넣지 마십시오. 과도하게 큰 요청 본문은 gateway / timeout 계층에서 실패하기 쉽습니다. 각 이미지를 **1.5MB 이내**로 압축하는 것이 가장 안정적이며, 출력 품질은 입력 파일 크기와 무관합니다. 이 오류(`code: invalid_image_file`)는 **N번째 참조 이미지가 표준 png / jpg / webp 파일이 아님**을 의미합니다(1부터 시작하는 인덱스이므로, 인덱스로 문제의 이미지를 찾으십시오). 가장 흔한 근본 원인은 휴대폰 카메라의 **MPO 형식**입니다. `.jpg` 파일은 Huawei Mate 시리즈 폰에서 바로 나온 경우 HDR gain-map 서브 프레임을 포함하며, 실제로는 다중 프레임 JPEG 컨테이너(MPO)입니다. 헤더는 동일한 `FFD8`이며, 확장자와 `file` 명령 모두 JPEG로 표시되므로 육안으로는 판별할 수 없습니다. 2026년 7월 검증 결과, MPO 파일은 항상 거부되며 동일한 이미지를 표준 JPEG/PNG로 다시 인코딩하면 **원본 해상도 그대로** 성공합니다(해상도, `image[]` 필드명, `quality`/`size` 파라미터와 무관). 이 오류는 입력 검증 단계에서 반환되며 **과금되지 않습니다**. **해결책**: 업로드 전에 Pillow로 다시 인코딩하십시오(`Image.open(f).format`가 `"MPO"`를 반환한다면 변환이 필요합니다). ```python theme={null} from PIL import Image im = Image.open("photo.jpg") im.load() # for MPO, keeps only the first frame im.convert("RGB").save("photo_fixed.jpg", quality=92) ``` 전체 세부 사항과 감지 방법: [Image Edit API — 참조 이미지 형식 요구 사항 및 전처리](/ko/api-capabilities/gpt-image-2/image-edit#reference-image-format-requirements-and-preprocessing). * 원본과 **같은 크기**, **PNG 형식**, **4MB 미만** * **알파 채널이 있어야 함**: 투명(alpha=0) = inpaint 영역, 불투명 = 유지 * 첫 번째 이미지에만 적용됨 * 마스크는 “소프트 가이드”이므로 모델이 마스크 영역 주변을 확장하거나 축소할 수 있습니다. | 선택 | 사용 시 | | ------------------------- | ----------------------------------------------------------------------------- | | **gpt-image-2** (공식) | 정밀한 크기/품질 제어가 필요하고, OpenAI 공식과 정확히 일치해야 하며, 4K 출력을 원하고, 마스크 inpainting이 필요할 때 | | **gpt-image-2-all** (리버스) | 이미지당 고정 \$0.03, 30\~60초 렌더링, 최소한의 매개변수, 높은 일관성 / 중국어 텍스트를 원할 때 | 예 — 코드 변경 없이 가능합니다. `base_url`를 `https://api.apiyi.com/v1`로 지정하고 `api_key`를 APIYI token으로 설정하십시오. ```python theme={null} from openai import OpenAI client = OpenAI(api_key="sk-your-key", base_url="https://api.apiyi.com/v1") resp = client.images.generate(model="gpt-image-2", prompt="...", size="2048x1152", quality="high") ``` **아니요**. `gpt-image-2`는 OpenAI의 공식 동기식 엔드포인트를 사용하므로, 요청이 제출되면 “취소” 신호 없이 완료될 때까지 실행됩니다. 클라이언트가 연결을 끊어도 서버는 생성을 끝까지 수행하고 정상적으로 과금합니다. 클라이언트 측 타임아웃을 신중하게 구성하십시오 — “연결 끊김 = 과금 없음”이라고 가정하면 안 됩니다. 기본값은 **100 RPM**(분당 100 requests)입니다. 실제로 사용할 수 있는 RPM은 **플랫폼 전체 동시 실행 수**에 따라 동적으로 조정됩니다. 워크로드에 더 많은 용량이 필요하면 예상 QPS / RPM을 알려 주십시오. 추가 용량을 제공할 수 있습니다. **아니요**. `gpt-image-2`는 OpenAI 공식 API를 엄격하게 그대로 따르며, 동기식만 지원합니다. 요청은 결과가 반환될 때까지 블록됩니다(`high` + 4K는 현실적으로 1\~2분). 비동기 큐나 콜백 메커니즘이 필요하면: * 비즈니스 계층에서 작업 큐(Celery / BullMQ 등)로 직접 감싸서 사용하십시오. * 또는 [`gpt-image-2-all`](/ko/api-capabilities/gpt-image-2-all/overview)를 사용하십시오 — 30\~60초 안에 생성되며 프런트엔드에서 폴링하기 더 쉽습니다. **아니요**. OpenAI의 기본 콘텐츠 모더레이션이 안전하지 않거나 형식이 잘못된 요청을 `400` 오류로 거부하며, **과금은 발생하지 않습니다**. 일반적인 응답은 다음과 같습니다. ```json theme={null} { "status_code": 400, "error": { "message": "Your request was rejected by the safety system. ...", "type": "shell_api_error", "code": "moderation_blocked" } } ``` 기타 무과금 오류: `401`(잘못된 token), `429`(요청 제한). **token 과금은 요청이 실제로 모델 생성 단계에 도달한 뒤에만 시작됩니다**(즉, `200` + `b64_json`를 수신한 이후). ## 관련 문서 * [⚖️ 공식 vs 역공학 비교](/ko/api-capabilities/gpt-image-2/vs-gpt-image-2-all) - 나란히 비교하는 선택 가이드 * [텍스트-이미지 플레이그라운드](/ko/api-capabilities/gpt-image-2/text-to-image) - `/v1/images/generations` 대화형 테스트 * [이미지 편집 플레이그라운드](/ko/api-capabilities/gpt-image-2/image-edit) - `/v1/images/edits` 다중 이미지 융합 + 마스크 * [심층 분석: gpt-image-2 출시](/en/news/gpt-image-2-launch) - 뉴스 기사 * [전체 통합 문서](/ko/api-capabilities/gpt-image-2/overview) - 완전한 API 참고서 * [GPT-Image-2-All (역공학)](/ko/api-capabilities/gpt-image-2-all/overview) - 더 저렴하고 더 빠른 대안 * [커뮤니티: Luck GPT-Image 2 ComfyUI 노드](/ko/scenarios/ecosystem/luckgpt2-comfyui) - ComfyUI에서 `gpt-image-2`을 직접 호출합니다 (마스크 / 5개 참고 이미지 / 사용자 지정 크기) * [커뮤니티: APIYI GPT-Image 2 스킬](/ko/scenarios/ecosystem/apiyi-gpt-image-skills) - Codex CLI / Cursor / Gemini CLI 및 기타 AI 코딩 도구에서 한 문장으로 호출합니다 * [API 설명서](/ko/api-manual) - 일반 사용 가이드 `gpt-image-2`는 OpenAI의 공식 플래그십이며, token 기준으로 과금됩니다. 정액 요금(\$0.03/image)과 더 빠른 생성(30–60초)을 우선한다면 [gpt-image-2-all](/ko/api-capabilities/gpt-image-2-all/overview)을 참고하십시오.