> ## 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.

# 이미지 압축 및 출력 해상도

> 이미지 API 호출에서 가장 자주 혼동되는 두 가지 질문, 즉 출력 해상도를 무엇이 결정하는지와 입력 참조 이미지를 압축하면 출력이 흐려지는지에 대한 혼란을 해소합니다.

이 페이지는 API를 통해 이미지 생성/편집 모델을 호출하는 개발자를 위한 페이지입니다. 가장 자주 혼동하는 두 가지 질문, 즉 **① 출력 이미지의 해상도는 무엇이 결정합니까? ② 입력 참조 이미지를 압축하면 출력이 흐려집니까?** 를 명확히 설명합니다. 이 결론은 특정 제품 UI와 무관하게 Nano Banana, GPT image, SeeDream, Flux 및 다른 이미지 모델에 모두 적용됩니다.

## 두 가지 전혀 다른 것

이미지 모델을 호출할 때는 두 가지 "해상도"가 있습니다. 이 둘은 요청에서 **서로 독립적인 필드**이므로 헷갈리지 마십시오.

|              | 입력 이미지 해상도 / 압축                                             | 출력 이미지 해상도                                                |
| ------------ | ----------------------------------------------------------- | --------------------------------------------------------- |
| 무엇을 의미하는지    | 업로드하는 **참조 이미지 / 편집할 이미지**의 크기/픽셀 수                         | 모델이 **생성하는** 이미지의 크기/픽셀 수                                 |
| 무엇이 이를 결정하는지 | 업로드하기 전에 적용하는 압축                                            | 요청의 **size 매개변수** (`size` / `imageSize` / `aspect_ratio`) |
| 요청에서 어디에 있는지 | 이미지 데이터 필드(예: `inline_data.data`, `image[]`, `input_image`) | size 매개변수 필드 — 이미지 데이터와는 **완전히 무관합니다**                    |

**한 문장으로 말하면**: 압축은 "입력하는 이미지"에 영향을 주고, 해상도 매개변수는 "모델이 뱉어내는 이미지"를 제어합니다. 각각 자기 일만 신경 씁니다.

## 품질을 압축하는가, 차원을 압축하는가? “압축”이 실제로 줄이는 것

“압축”은 느슨하게 쓰이지만, 이미지에는 서로 독립적인 두 가지 “크기”가 있으며 각각에 다른 압축 레버가 있습니다:

|           | 픽셀 차원(해상도)                           | 파일 크기                                                |
| --------- | ------------------------------------ | ---------------------------------------------------- |
| 무엇을 가리키는지 | 픽셀 단위의 너비 × 높이, 예: `4284×5712`       | 디스크/대역폭 사용량, 예: 4.6 MB                               |
| 무엇이 결정하는지 | 캡처/생성 시점의 해상도                        | 픽셀 수 × 인코딩 품질 × 시각적 복잡도                              |
| 압축 레버     | **리사이즈**: 가장 긴 변을 비율대로 줄여 픽셀 수를 줄입니다 | **재인코딩**: 손실 JPEG/WebP 인코딩으로 같은 픽셀 수에서 파일을 더 작게 만듭니다 |

이 둘은 서로 크게 불균형할 수 있습니다. 실제 예시입니다(실측값이며, 인코딩에 따라 달라집니다):

* iPhone 16 Pro로 찍은 사진은 **4284×5712**(약 2400만 픽셀로 매우 큽니다)인데도 파일은 **4.6 MB**에 불과합니다. 저장할 때 이미 효율적인 손실 인코딩이 적용되었기 때문입니다;
* 같은 픽셀 수의 사진이라도 높은 품질로 내보내면 **30 MB**에 이를 수 있습니다.

따라서 “이 이미지를 압축해야 하는가”는 픽셀만으로도 파일 크기만으로도 판단할 수 없습니다. 서로 다른 단계에 영향을 미치기 때문입니다:

* **픽셀 차원**은 모델이 “볼 수 있는” 정보의 상한과 디코딩/이해 비용을 정합니다;
* **파일 크기**는 전송 비용을 좌우합니다. 약 33%의 Base64 부풀림, 업로드 시간, 20 MB 단일 파일 상한은 모두 바이트를 기준으로 합니다.

<Tip>
  **실용적인 권장사항은 순서대로 둘 다 하는 것입니다**: 먼저 픽셀에 상한을 두고(가장 긴 변을 비율대로 2048px 이하로 줄임), 그다음 품질을 상한으로 두십시오(0.9로 재인코딩). 그리고 **파일 크기를 트리거로 사용하십시오**(1.5 MB를 넘는 파일만 처리). 위의 4.6 MB 사진은 두 단계를 모두 거치게 됩니다. 4284px 변은 2048px로 줄어들고, 이어서 품질 0.9로 재인코딩되며, 보통 파일은 1 MB 아래로 내려가지만 모델이 이를 이해하는 정도에는 영향을 주지 않습니다.
</Tip>

## 출력 해상도는 prompt가 아니라 size 매개변수로 정해집니다

이것이 가장 흔한 오해이므로, 결론부터 말씀드립니다:

<Warning>
  **prompt에 "4K", "HD", "ultra-clear" 또는 "8K"를 적어도 출력이 4K가 되지는 않습니다.** 실제 출력 해상도는 **요청의 size 매개변수에만 의존합니다**. prompt는 "무엇을 그릴지"를 제어할 뿐, "출력 크기가 얼마나 클지"는 제어하지 않습니다.
</Warning>

모델마다 사용하는 size 매개변수는 다릅니다. 일반적인 것은 다음과 같습니다:

| 모델 계열                                          | 출력 크기를 제어하는 매개변수                                    | 값 형식             | 예시                                       |
| ---------------------------------------------- | --------------------------------------------------- | ---------------- | ---------------------------------------- |
| **Gemini image 시리즈** (예: `gemini-3-pro-image`) | `imageConfig.imageSize` + `imageConfig.aspectRatio` | **티어 문자열** + 비율  | `imageSize: "4K"`, `aspectRatio: "16:9"` |
| **GPT image 시리즈** (gpt-image 등)                | `size`                                              | **픽셀 문자열 `WxH`** | `size: "2048x2048"`                      |
| **SeeDream 시리즈**                               | `size`                                              | 픽셀 문자열 / 티어      | `size: "2048x2048"`                      |
| **Flux 시리즈**                                   | `aspect_ratio` 또는 `width` + `height`                | 비율 문자열 / 픽셀      | `aspect_ratio: "16:9"`                   |

### 예시: gemini-3-pro-image

이 모델은 **`imageSize`** 티어를 통해 출력 해상도를 제어합니다. \*\*`1K` / `2K` / `4K`\*\*를 사용하며, 생략하면 기본값은 `1K`입니다. 또한 `aspectRatio`가 프레임 비율을 제어합니다:

```json theme={null}
{
  "contents": [ /* prompt text + input images (if any) */ ],
  "generationConfig": {
    "responseModalities": ["IMAGE"],
    "imageConfig": {
      "aspectRatio": "16:9",
      "imageSize": "4K"
    }
  }
}
```

`imageSize`는 실제로 출력 해상도를 결정하는 필드입니다. 각 비율 + 티어는 고정된 픽셀 크기에 매핑됩니다. 예를 들어 1:1에서 1K/2K/4K는 대략 `1024×1024 / 2048×2048 / 4096×4096`이고, 16:9는 대략 `1376×768 / 2752×1536 / 5504×3072`입니다.

### GPT image 시리즈는 size 픽셀 문자열을 사용합니다

```json theme={null}
{
  "model": "gpt-image-...",
  "prompt": "...",
  "size": "2048x2048"
}
```

<Tip>
  **핵심 포인트**: 4K를 원하시면 size 매개변수를 일치하는 티어/픽셀 값으로 설정하십시오(예: `imageSize:"4K"` 또는 `size:"4096x4096"`). **prompt에 "4K"를 적으면 안 됩니다.** prompt와 size 매개변수는 요청에서 서로 독립적인 두 필드이며, 엔진은 해상도를 조정하기 위해 prompt에서 "4K"를 파싱하지 않습니다.
</Tip>

<Info>
  일부 모델(특정 적응형 출력 유형)은 **size 매개변수를 허용하지 않습니다**. 출력 해상도는 모델 자체에 의해 결정됩니다(보통 1\~1.5K 정도입니다). 이러한 모델은 파라미터로도 4K를 강제할 수 없으며, prompt로는 더더욱 불가능합니다. 각 모델의 문서/기능 설명을 확인하십시오.
</Info>

<Warning>
  **지원되는 `imageSize` 티어도 동일한 모델 계열 내에서 다를 수 있습니다.** 예를 들어 Gemini image 라인업에서는 `gemini-3-pro-image`가 `1K`/`2K`/`4K`를 지원하지만, Nano Banana 2 Lite (`gemini-3.1-flash-lite-image`)는 **`1K`만 허용합니다**. `2K`/`4K`를 전달하면 오류가 반환됩니다. 모델을 전환할 때는 같은 계열의 다른 모델에서 사용하던 매개변수를 재사용하지 말고, 반드시 해당 모델이 지원하는 티어를 확인하십시오.
</Warning>

## 입력 이미지를 압축해도 출력 선명도가 떨어지나요? 사실상 아닙니다

결론: **대부분의 시나리오에서 입력 참조 이미지를 적절히 압축해도 출력 선명도에는 거의 영향이 없습니다.** 이유는 세 가지입니다.

1. **출력은 업스케일이 아니라 새로 생성됩니다.**
   모델은 지정한 크기대로 **새 이미지를 그려냅니다.** 출력 해상도는 `imageSize`/`size`에만 따라 결정되며, 입력 이미지의 픽셀 수와는 무관합니다. 입력이 3000px이든 2000px로 압축되었든, 4K를 선택하면 4K가 출력됩니다.

2. **입력 압축 필드와 출력 크기 필드는 서로 독립적입니다.**
   압축은 요청의 "image data" 필드의 용량/픽셀 수만 바꾸며, 크기 파라미터 필드에는 **절대 영향을 주지 않습니다.** 요청에서 두 항목은 서로 관련이 없습니다.

3. **권장 압축은 완만하며, 모델이 이미지를 "보는" 데 필요한 수준보다 훨씬 높습니다.**
   실제로 참조 이미지를 **긴 변 기준 약 2048px, JPEG 품질 약 0.9**로 압축하는 것만으로도 모델이 구도, 색상, 스타일, 주제 세부 사항을 이해하기에 충분합니다. 이런 모델들은 내부적으로 인코딩하기 전에 입력 이미지를 어차피 적당한 해상도로 축소합니다.

### 엄밀히 보자면: 예외 사례

**이미지-투-이미지 / 세밀 편집** 작업에서(입력의 특정 영역에 있는 아주 작은 텍스처나 작은 텍스트를 엄격하게 보존해야 하는 경우), 입력을 **너무 공격적으로** 압축하면(예: 긴 변을 수백 픽셀 수준으로 줄이거나 품질을 0.5 미만으로 낮추는 경우) 이론적으로 일부 디테일이 손실되어 편집이 원본을 얼마나 충실하게 보존하는지에 간접적으로 영향을 줄 수 있습니다.

하지만 "긴 변 ≤ 2048px, 품질 ≥ 0.85" 같은 완만한 기준을 따르면, 실제 사용에서는 이 영향이 **무시할 만한 수준**입니다. 더 정확히 말하면:

> **적절한 압축**(긴 변 2048px, 품질 0.9) → 출력 선명도에 **체감 가능한 영향 없음**;
> **극단적인 과압축**만이 세밀 편집 시나리오에서 디테일 손실을 일으킬 수 있습니다.

## 입력 이미지에 대한 실용적인 압축 설정

호출하기 전에 입력 이미지를 압축한다면, 다음의 완만한 기준을 권장합니다 — 유용한 정보를 잃지 않으면서 대역폭을 절약할 수 있습니다:

| 항목           | 권장 값                        | 참고                                               |
| ------------ | --------------------------- | ------------------------------------------------ |
| 압축 트리거 임계값   | 원본 > **1.5 MB**             | 작은 이미지는 압축할 필요가 없습니다 — 그대로 보내십시오                 |
| 긴 변의 상한      | **2048 px**                 | 비율에 맞게 조정하고, 종횡비를 유지하며, 작은 이미지는 **절대 확대하지 마십시오** |
| 압축 품질        | **0.9** (0–1)               | 고품질로, 눈에는 사실상 무손실입니다                             |
| 출력 형식        | **원본 형식 유지** (JPG/PNG/WebP) | 강제로 변환하지 마십시오; 투명도가 필요하면 PNG/WebP를 사용하십시오        |
| 여러 이미지의 총 크기 | **\~6 MB** 이하로 유지           | 여러 참조 이미지를 사용할 때는 이미지별 예산을 적응적으로 분할하십시오          |
| 단일 파일 상한     | **≤ 20 MB**                 | 업로드 시간 초과/거절을 피하려면 먼저 너무 큰 파일을 압축하십시오            |

적응형 다중 이미지 접근 방식: `per-image target = clamp(total budget ÷ image count, 0.3MB, 1.5MB)`. 이미지가 많을수록 이미지별 몫은 더 작아지며, 총합은 제어된 상태로 유지됩니다. 이미 목표 범위 안에 있는 이미지는 그대로 통과시킵니다.

<Tip>
  **장애 허용성**: 압축은 있으면 좋은 기능입니다 — 대체 경로를 유지하십시오. **이미지 압축에 실패하면 원본으로 되돌려 계속 진행하십시오**; 압축 단계가 실패했다고 해서 전체 생성 요청을 절대 중단하지 마십시오.
</Tip>

## 후속 워크플로에 들어가는 생성 이미지: 이것도 처리하십시오

API로 생성된 이미지는 예상보다 큰 경우가 많습니다. Nano Banana Pro의 4K 티어를 예로 들면 됩니다(경험적 수치이며, 채널별 인코딩에 따라 달라집니다).

| 채널           | 4K 이미지당 일반적인 크기 |
| ------------ | --------------- |
| AI Studio 채널 | \~**9 MB**      |
| Vertex 채널    | \~**18 MB**     |

같은 4K 티어라도 채널마다 인코딩 방식이 달라 파일 크기가 2배까지 차이 날 수 있습니다.

생성된 이미지가 다음 단계의 입력이 된다면(재편집, 다중 이미지 합성, 참조 이미지), **입력 이미지와 동일한 기준(가장 긴 변 2048px, 품질 0.9)으로 먼저 압축하십시오**. 그렇지 않으면 18 MB 이미지가 Base64 인코딩 오버헤드 약 33% 때문에 대략 24 MB로 불어나며 — 요청 본문/단일 파일 제한에 쉽게 걸리고 업로드도 느려집니다. Base64 팽창 세부 사항은 [Nano Banana 시리즈 개발자 가이드](/ko/api-capabilities/nano-banana-dev-guide)를 보십시오.

<Tip>
  후속 사용 ≠ 원본 그대로의 상태가 필요하다는 뜻은 아닙니다. 중간 워크플로 이미지는 “모델이 이해할 수 있는” 기준으로 압축하십시오. 최종 결과물이 4K를 필요로 한다면, 4K는 **마지막 단계에서만** 생성하고, 그 사이에는 속도와 비용을 위해 1K/2K로 반복하십시오.
</Tip>

생성된 이미지가 단지 표시/보관용이고 다시 모델로 돌아가지 않는다면, [Nano Banana OSS 그룹](/ko/api-capabilities/nano-banana-oss-group)을 고려하십시오. 이미지는 URL로 반환되므로 Base64 전송 오버헤드를 피할 수 있습니다.

## 추가 이미지 처리 모범 사례

압축 외에도, API 호출 시나리오에서 업로드 전에 다음 사항을 처리하는 것이 좋습니다:

* **EXIF 방향 정보를 픽셀에 반영합니다**: 휴대폰 사진은 회전 정보를 픽셀 자체가 아니라 EXIF Orientation 태그에 저장하는 경우가 많습니다. 일부 처리 파이프라인은 이 태그를 무시하므로, 모델은 옆으로 눕거나 거꾸로 된 이미지를 보게 됩니다. 업로드 전에 회전을 픽셀에 적용하십시오(대부분의 압축 라이브러리는 다시 인코딩할 때 이를 자동으로 수행합니다).
* **업로드 전에 EXIF 개인정보 메타데이터를 제거합니다**: 원본 사진에는 종종 EXIF에 GPS 좌표, 기기 모델, 촬영 시간이 포함됩니다. 사용자 사진을 서드파티 API로 전송하기 전에 메타데이터를 제거하십시오 — 다시 인코딩하면 보통 부수적으로 제거되지만, 순서에 유의해야 합니다: **먼저 방향을 적용하고, 그다음 제거합니다**.
* **형식 호환성**: iPhone의 기본 HEIC/HEIF 형식은 대부분의 이미지 API에서 지원되지 않습니다 — 먼저 JPEG/PNG로 변환하십시오; 투명도가 필요하면 PNG/WebP를 사용하십시오; 애니메이션 GIF는 보통 첫 프레임만 읽힙니다.
* **색공간을 sRGB로 변환합니다**: Apple 기기 사진은 흔히 Display P3를 사용합니다. 색상 프로파일을 무시하는 파이프라인은 색상 변이를 일으킵니다 — 업로드 전에 sRGB로 변환하십시오.
* **상황에 맞는 전송 방법을 선택합니다**: 입력 측에서는 Base64가 가장 안정적입니다; URL (`fileUri`) 업로드는 엄격한 CDN 요구사항이 있습니다 — 장단점은 [Nano Banana Series Developer Guide](/ko/api-capabilities/nano-banana-dev-guide)를 참고하십시오. 출력 측에서는 [Nano Banana OSS Group](/ko/api-capabilities/nano-banana-oss-group)을 사용하여 Base64 대신 URL을 받으십시오.
* **실제로 필요한 출력 등급을 선택합니다**: 결과물에 4K가 꼭 필요하지 않다면 요청하지 마십시오 — 생성 속도가 느려지고, 파일이 커지며, 후속 전송/처리 비용도 높아집니다. 1K/2K에서 반복하고, 최종 렌더링에만 4K로 전환하십시오.
* **URL 출력은 즉시 저장합니다**: API가 반환하는 이미지 URL은 만료됩니다. 받는 즉시 자체 저장소로 옮기십시오 — 임시 URL을 영구 자산으로 취급해서는 안 됩니다.

## 빠른 참조

* **출력 해상도 = 크기 파라미터** (`imageSize` / `size` / `aspect_ratio`)이며, **prompt의 텍스트가 아닙니다**. 4K가 필요하시면 파라미터를 설정하시고 prompt에 적지 마십시오.
* `gemini-3-pro-image`는 등급이 **1K / 2K / 4K**인 `imageSize`를 사용합니다(기본값 1K). GPT image 시리즈는 `size` 픽셀 문자열을 사용합니다.
* **입력 압축과 출력 해상도는 서로 관련이 없습니다** — 요청의 두 개의 독립된 필드입니다.
* **픽셀 크기와 파일 크기는 서로 다른 개념입니다**: 압축은 먼저 크기 조정(긴 변 2048px) 후 재인코딩(품질 0.9)이며, 파일 크기를 기준으로 사용하십시오(1.5MB 초과 시에만).
* **적절한 입력 압축(긴 변 2048px, 품질 0.9)은 출력 선명도에 영향을 주지 않습니다**. 극단적인 과도 압축만 세밀한 편집에서 디테일을 잃을 수 있습니다.
* 권장 입력 압축: 1.5MB 초과 시에만 압축, 긴 변 ≤2048px, 품질 0.9, 원본 형식 유지, 다중 이미지 총합 ≤6MB, 단일 파일 ≤20MB, 실패 시 원본으로 되돌림.
* **다운스트림 워크플로에 넣기 전에 생성된 이미지를 압축하십시오**: Nano Banana Pro 4K 이미지는 이미지당 약 9\~18MB가 소요됩니다(채널에 따라 다름) — 그대로 다시 보내면 쉽게 한도에 도달합니다.
* **업로드 전에 EXIF와 형식을 처리하십시오**: 방향 정보를 픽셀에 반영하고, GPS 및 기타 개인정보 메타데이터를 제거하며, HEIC를 JPEG로 변환하고, Display P3를 sRGB로 변환하십시오.

## 관련 문서

* [Nano Banana 시리즈 개발자 가이드](/ko/api-capabilities/nano-banana-dev-guide)
* [사용 필드 및 출력 설명](/ko/api-capabilities/nano-banana-usage-metadata)
* [Gemini Image API 오류 처리 가이드](/ko/api-capabilities/gemini-image-error-handling)