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

## 压缩输入图，会不会影响出图清晰度？基本不会

结论：**对绝大多数场景，合理压缩输入参考图，几乎不影响输出图的清晰度。** 原因有三：

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 系列开发指南](/api-capabilities/nano-banana-dev-guide)。

<Tip>
  下游用图 ≠ 需要保真原图。工作流的中间图按「模型看得懂」的标准压即可；如果终稿需要 4K 交付，只在**最后一步**出 4K，中间迭代用 1K/2K，又快又省。
</Tip>

如果产出图只用于展示/存档、不回传模型，可考虑 [Nano Banana OSS 分组](/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 系列开发指南](/api-capabilities/nano-banana-dev-guide)；输出侧不想处理 Base64 可用 [Nano Banana OSS 分组](/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 系列开发指南](/api-capabilities/nano-banana-dev-guide)
* [usage 字段与输出解读](/api-capabilities/nano-banana-usage-metadata)
* [Gemini 生图 API 错误处理指南](/api-capabilities/gemini-image-error-handling)