> ## 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 呼叫影像生成/編輯模型的開發者，澄清兩個最常被混淆的問題：**① 輸出圖的解析度由什麼決定？② 對輸入參考圖做壓縮，會不會讓出圖變糊？** 結論適用於 Nano Banana、GPT 影像、SeeDream、Flux 等各類影像模型，與具體產品介面無關。

## 先分清兩件完全不同的事

呼叫影像模型時，有兩個「解析度」，它們在請求裡是**互相獨立的兩個欄位**，不要混為一談：

|         | 輸入圖解析度 / 壓縮                                          | 輸出圖解析度                                              |
| ------- | ---------------------------------------------------- | --------------------------------------------------- |
| 指什麼     | 你上傳的**參考圖 / 待編輯圖**的大小、畫素                             | 模型**生成出來**那張圖的大小、畫素                                 |
| 由誰決定    | 你在上傳/請求前對圖片做的壓縮處理                                    | 請求裡的**尺寸引數**（`size` / `imageSize` / `aspect_ratio`） |
| 在請求裡的位置 | 圖片資料欄位（如 `inline_data.data`、`image[]`、`input_image`） | 尺寸引數欄位，與圖片資料**毫不相干**                                |

**一句話**：壓縮的是「你喂進去的圖」，解析度引數控制的是「模型吐出來的圖」。兩者各管各的。

## 壓縮品質還是壓縮尺寸？先搞懂「壓縮」壓的是什麼

「壓縮」這個詞經常被籠統使用，實際上圖片有兩個互相獨立的「大小」，對應兩種不同的壓縮手段：

|         | 畫素尺寸（解析度）               | 檔案體積                              |
| ------- | ----------------------- | --------------------------------- |
| 指什麼     | 圖片長寬各多少畫素，如 `4284×5712` | 檔案佔多少磁碟/頻寬，如 4.6 MB               |
| 由什麼決定   | 拍攝/生成時的解析度設定            | 畫素數 × 編碼品質 × 畫面複雜度                |
| 對應的壓縮手段 | **縮尺寸**：等比縮小長邊，畫素變少     | **降品質**：JPEG/WebP 有損重編碼，畫素不變、體積變小 |

兩者可以嚴重不成比例。一個真例項子（經驗值，具體隨編碼實現變化）：

* iPhone 16 Pro 拍的一張照片，尺寸 **4284×5712**（約 2400 萬畫素，很大），檔案體積卻只有 **4.6 MB**——因為系統儲存時已經做了高效率的有損編碼；
* 同樣畫素的照片如果以高品質直出，體積可能接近 **30 MB**。

所以「這張圖要不要壓」不能只看畫素，也不能只看體積——兩者影響的環節不同：

* **畫素尺寸**決定模型「看圖」能獲得的資訊量上限，以及解碼/理解的處理成本；
* **檔案體積**決定傳輸環節的成本：Base64 編碼膨脹約 33%、上傳耗時、單檔案 20 MB 上限，衝著的都是體積。

<Tip>
  **實踐建議是雙管齊下、按序執行**：先限畫素（長邊 ≤ 2048px 等比縮小），再限品質（重編碼品質 0.9）；而**是否觸發處理看體積**（大於 1.5 MB 才處理）。上面那張 4.6 MB 的照片兩步都會做：4284px 長邊縮到 2048px、再以 0.9 品質重編碼，體積通常降到 1 MB 以內，對模型理解毫無影響。
</Tip>

## 輸出解析度由「尺寸引數」決定，不由提示詞決定

這是最常見的誤解，結論先行：

<Warning>
  **在 prompt 裡寫「4K」「高畫質」「超清」「8K」並不會讓輸出變成 4K。** 實際輸出解析度**只取決於請求裡的尺寸引數**。提示詞只負責「畫什麼內容」，不負責「出多大尺寸」。
</Warning>

不同模型用不同的尺寸引數，常見的幾類：

| 模型類別                                    | 控制輸出尺寸的引數                                           | 取值形式           | 示例                                      |
| --------------------------------------- | --------------------------------------------------- | -------------- | --------------------------------------- |
| **Gemini 影像系列**（如 `gemini-3-pro-image`） | `imageConfig.imageSize` + `imageConfig.aspectRatio` | **檔位字串** + 比例  | `imageSize: "4K"`、`aspectRatio: "16:9"` |
| **GPT 影像系列**（gpt-image 等）               | `size`                                              | **畫素字串 `寬x高`** | `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 文本 + 輸入圖（如有）*/ ],
  "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 影像系列以 size 畫素串控制

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

<Tip>
  **要點**：想要 4K，就把尺寸引數設成對應檔位/畫素（如 `imageSize:"4K"` 或 `size:"4096x4096"`），**而不是在 prompt 裡寫「4K」**。提示詞和尺寸引數在請求裡是兩個獨立欄位，引擎不會去解析 prompt 裡的「4K」字樣來調整解析度。
</Tip>

<Info>
  個別模型（如某些自適應出圖的型號）**不接受尺寸引數**，輸出解析度由模型自行決定（通常約 1–1.5K）。這類模型即使想要 4K 也無法通過引數強制，更不可能靠提示詞實現。以各模型文件/能力宣告為準。
</Info>

<Warning>
  **同一模型系列內部，`imageSize` 可選檔位也不統一**：以 Gemini 影像系列為例，`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. **輸入圖壓縮欄位與輸出尺寸欄位彼此獨立。**
   壓縮只改變請求裡「圖片資料」那個欄位的體積/畫素，**完全不碰**尺寸引數欄位。兩者在請求裡沒有任何關聯。

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**             | 超大檔案先壓再傳，避免上傳超時/被拒     |

多圖自適應思路：`單張目標體積 = clamp(總預算 ÷ 張數, 0.3MB, 1.5MB)`。張數越多、每張分攤越小，保證合計可控；已達標的圖原樣通過、不二次壓縮。

<Tip>
  **容錯建議**：壓縮屬於「錦上添花」，請保留兜底——**某張圖壓縮失敗時回退用原圖繼續**，不要因為壓縮環節失敗而中斷整個生成請求。
</Tip>

## 生成圖用於下游工作流：同樣建議先處理

API 產出的圖片往往比想像中大。以 Nano Banana Pro 的 4K 檔位為例（實測經驗值，具體隨渠道編碼實現變化）：

| 渠道           | 4K 單張典型體積   |
| ------------ | ----------- |
| AI Studio 渠道 | 約 **9 MB**  |
| Vertex 渠道    | 約 **18 MB** |

同為 4K 檔位，不同渠道的編碼實現不同，體積可以差一倍。

如果要把產出圖作為下一環節的輸入（再編輯、多圖合成、當參考圖），**按輸入圖的同一標準先壓縮再傳**（長邊 2048px、品質 0.9）。否則一張 18 MB 的圖經 Base64 膨脹約 33% 後約 24 MB，很容易觸頂請求體/單檔案限制，還拖慢上傳。Base64 膨脹細節見 [Nano Banana 系列開發指南](/zh-Hant/api-capabilities/nano-banana-dev-guide)。

<Tip>
  下游用圖 ≠ 需要保真原圖。工作流的中間圖按「模型看得懂」的標準壓即可；如果終稿需要 4K 交付，只在**最後一步**出 4K，中間迭代用 1K/2K，又快又省。
</Tip>

如果產出圖只用於展示/存檔、不回傳模型，可考慮 [Nano Banana OSS 分組](/zh-Hant/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**：蘋果裝置照片常用 Display P3 色彩空間，部分處理鏈路不識別色彩描述檔案會產生色偏，建議上傳前轉成 sRGB。
* **傳輸方式按場景選**：輸入側 Base64 最穩，URL（`fileUri`）上傳對圖床/CDN 要求高，取捨見 [Nano Banana 系列開發指南](/zh-Hant/api-capabilities/nano-banana-dev-guide)；輸出側不想處理 Base64 可用 [Nano Banana OSS 分組](/zh-Hant/api-capabilities/nano-banana-oss-group) 直接拿 URL。
* **按需選擇輸出檔位**：不需要 4K 交付就別請求 4K——生成更慢、體積更大、下游傳輸和處理成本更高。中間迭代用 1K/2K，確認滿意後終稿再上 4K。
* **URL 輸出及時轉存**：以 URL 形式返回的圖片連結有時效，拿到後及時轉存到自有儲存，不要把臨時 URL 當永久資源引用。

## 速查總結

* **輸出解析度 = 尺寸引數**（`imageSize` / `size` / `aspect_ratio`），**不是 prompt 裡的文字**。想要 4K，請設引數，別寫在提示詞裡。
* `gemini-3-pro-image` 用 `imageSize`，檔位 **1K / 2K / 4K**（預設 1K）；GPT 影像系列用 `size` 畫素串。
* **輸入圖壓縮 與 輸出圖解析度 互不相干**，是請求裡兩個獨立欄位。
* **畫素尺寸和檔案體積是兩回事**：壓縮 = 先縮邊（長邊 2048px）再降質（0.9），是否處理看體積（大於 1.5MB 才壓）。
* **合理壓縮輸入圖（長邊 2048px、品質 0.9）不影響輸出清晰度**；只有極端過度壓縮才可能在精細編輯裡掉細節。
* 輸入壓縮推薦：大於 1.5MB 才壓、長邊 ≤2048px、品質 0.9、保持原格式、多圖合計 ≤6MB、單檔案 ≤20MB、失敗回退原圖。
* **生成圖進下游工作流前也要先壓縮**：Nano Banana Pro 4K 單張約 9–18 MB（隨渠道而異），直接回傳很容易觸頂限制。
* **上傳前處理好 EXIF 與格式**：方向烘焙進畫素、剝離 GPS 等隱私後設資料、HEIC 轉 JPEG、Display P3 轉 sRGB。

## 相關文件

* [Nano Banana 系列開發指南](/zh-Hant/api-capabilities/nano-banana-dev-guide)
* [usage 欄位與輸出解讀](/zh-Hant/api-capabilities/nano-banana-usage-metadata)
* [Gemini 生圖 API 錯誤處理指南](/zh-Hant/api-capabilities/gemini-image-error-handling)