
# 图片压缩API使用说明

[TOC]

## 基本概念与原理

### 常见格式与特性

- PNG（Portable Network Graphics）
  - 应用场景：UI 图标、插画、扁平色块、截图、需透明通道（Alpha）的素材、线稿/文本。
  - 特性：无损压缩、支持 8 位 alpha、锐利边缘保真；体积相对较大。

- JPG/JPEG（Joint Photographic Experts Group）
  - 应用场景：摄影类图片、复杂纹理、背景图、相册/电商商品图等。
  - 特性：有损压缩、体积小、解码快；不支持透明；高压缩率下边缘可能出现马赛克/振铃伪影。

- BMP（Bitmap）
  - 应用场景：极少直接用于网页；更常见于中间态或早期 Windows/设备生成图片。
  - 特性：可无压缩或简单压缩，体积大，兼容性好；通常作为过渡格式，建议转换为 WebP/AVIF。

- TIFF（Tagged Image File Format）
  - 应用场景：印刷、扫描、专业摄影/后期流程、高位深与多通道素材。
  - 特性：容器化、可无损/有损、多页、多通道；网页端不常直接分发，建议转 Web 友好格式。

- GIF（Graphics Interchange Format）
  - 应用场景：简单动画、少色动态图标/贴纸；也用于少色静态图。
  - 特性：最多 256 色调色板、支持 1 位透明；动画广泛但色深受限，体积通常偏大；适合转为 WebP 动画。

- WebP
  - 应用场景：网页分发的通用静/动态图，既要高压缩效率又需透明/动画支持的场景。
  - 特性：同时支持有损与无损、支持透明与动画（本项目已适配 GIF→WebP 动画转换）；普遍优于 JPEG/PNG 的压缩效率，浏览器支持广。

- AVIF（AV1 Image File Format）
  - 应用场景：追求更高压缩比/更优画质-体积比的网页/移动端静态图；对编码速度容忍度较高的场景。
  - 特性：基于 AV1 编码的静态图格式，支持有损/无损与透明；在相同主观质量下，体积通常小于 WebP，但编码更慢、老旧环境兼容性略差（本项目目前不处理 AVIF 动画）。

为什么 WebP/AVIF 的图片更小（核心原因）

- 更先进的变换/预测：
  - WebP（有损）基于 VP8 intra：块内预测 + DCT/副变换，灵活的块划分与方向预测；（无损）VP8L 使用多种可逆变换与局部预测。
  - AVIF 基于 AV1 intra：更丰富的方向内预测、可变块划分（更细粒度）、更强环路滤波与复原，重建质量更高、码率更低。
- 更高效的熵编码：
  - WebP 使用更优化的概率模型与 Huffman/布尔编码；AV1（AVIF）采用上下文自适应算术编码，逼近信息熵极限。
- Alpha/动画的高效编码：
  - WebP Alpha 可独立（可无损）编码；动画按帧差分与预测组织，显著减少冗余。
- 感知优化与子采样：
  - 灵活的色度子采样（如 4:2:0）与率失真优化，使在相同观感质量下占用更少比特。

### 什么是图片压缩

图片压缩通过去除冗余信息、利用人眼视觉特性，在尽量不影响观感的前提下降低文件体积。常见目标与取舍：

- 体积：更小的文件，提升传输与加载速度
- 画质：尽可能保留细节与锐度，避免明显失真
- 兼容性：是否可在目标平台/浏览器稳定显示
- 编码/解码耗时：压缩与解压速度、资源占用

### 有损 vs 无损

- 无损压缩：像素数据在解码后与原图完全一致。适合图标、UI 截图、插画、文本/线稿等对细节与锐利边缘敏感的图像。常见格式：PNG、WebP（无损）、部分 AVIF（无损模式）。
- 有损压缩：通过“量化”等方式丢弃一部分难感知的细节来显著减小体积。适合摄影类图片、复杂纹理、背景等。常见格式：JPEG、WebP（有损）、AVIF（有损）。
- 透明度：PNG、WebP、AVIF 均可支持透明通道（Alpha）；JPEG 不支持透明。

### 类型对比（速览）

用途与说明：此模块用于按关键维度快速横向对比不同“压缩类型/图片格式”，帮助在质量、体积、透明、动画、速度与兼容性之间做取舍与选型。

- 质量（主观观感）
  - 无损：零失真（PNG、WebP 无损、部分 AVIF 无损）。
  - 有损：轻度到明显失真（JPEG、WebP 有损、AVIF 有损）。在相同体积下，WebP/AVIF 通常优于 JPEG。

- 体积（同等主观质量）
  - 一般趋势：AVIF 最小 ≲ WebP < JPEG ≲ PNG（无损）。GIF 动图通常更大。
  - 本项目典型输出：优先 WebP（有损/无损）；可选 AVIF（静态，编码更慢）。

- 透明度（Alpha）
  - 支持：PNG、WebP、AVIF。
  - 受限/不支持：GIF（1 位透明）、JPEG（不支持）。

- 动画
  - 支持：WebP（本项目已实现 GIF→WebP 动画转换）。
  - 受限：GIF（色深受限、体积偏大）。
  - 不处理：AVIF 动画（本项目暂不处理）；PNG/JPEG 不支持动画。

- 编码/解码速度（经验）
  - 编码（快→慢）：JPEG ≈ WebP 有损 < WebP 无损 < AVIF。
  - 解码：普遍较快；AVIF 相对更慢但可接受，取决于平台支持。

- 可逆性与重复压缩
  - 无损：可逆、反复压缩不劣化。
  - 有损：不可逆，反复编解码会累计失真（建议保留原始素材）。

- 兼容性（生态支持）
  - 最佳：JPEG/PNG/GIF。
  - 良好：WebP（现代浏览器与平台广泛支持）。
  - 较新：AVIF（新平台支持提升中，老旧环境可能不佳）。

### 无损压缩：目的与底层原理

- 目的：
  - 逐点一致（bit‑exact），不引入任何视觉失真。
  - 保持锐利边缘/文本/线稿细节与透明通道。
  - 适用于对“像素正确性”有严格要求的内容。

- 预测与残差编码（predictive coding）：
  - 思想：相邻像素强相关，先用“预测器”估计当前像素，再编码“误差”（残差）。
  - PNG 滤波器（filters）：Sub/Up/Average/Paeth 等逐行预测，Paeth 使用邻近像素的线性预测并选择误差更小者。
  - WebP Lossless（VP8L）：使用多种变换与预测（如 subtract-green、局部预测器、颜色索引表）以降低熵。
- 变换与颜色处理：
  - 颜色索引（palette/indexing）：将常见颜色映射到小型调色板，像素以索引保存（对少色图高效）。
  - 颜色变换（color transform）：如 VP8L 的 subtract-green（先将 G 通道“提取”），降低通道间冗余。
- 字典与回溯引用：
  - LZ77/LZSS 类（字典压缩）：用“距离-长度（offset-length）”对重复串做回溯引用，避免重复字节存储。
  - WebP Lossless 的“滑动窗口”参考与元块（meta-blocks）组织，便于局部自适应。
- 熵编码（entropy coding）：
  - Huffman 编码：对高频符号使用短码，低频用长码，接近信息论中的最优编码。
  - DEFLATE（LZ77 + Huffman）：PNG 采用该组合；WebP Lossless 亦使用基于 Huffman 的熵模型。
- 可逆性与位深：
  - 可逆（reversible）：解码后像素值与原图逐点一致（如 PNG、WebP 的 lossless 模式）。
  - 位深（bit depth）：8/10/12 位等，位深越高对渐变等细节保真越好，体积也可能增加。

与本项目实现的对应：

- `image_lossless` / `image_force_lossless` 最终写出为 WebP 无损（Pillow → libwebp，`lossless=True`）。
- PNG/GIF 等输入图像的透明度（Alpha）在无损路径下保留；WebP 有损时 Alpha 通道也采用无损独立编码。
- `optimize`/`method` 会影响编码器的统计优化和搜索强度（更高通常更慢但压缩更好）。

术语补充：

- 预测器（predictor）：用上下文估计像素值的函数，如 Paeth。
- 残差（residual）：实际像素 − 预测值，分布更集中，便于熵编码。
- 调色板（palette）：颜色查找表，用较少比特表达颜色。
- 回溯引用（back-reference）：引用先前出现的字节串以替代当前串的存储。
- 熵（entropy）：信息不确定度的度量，低熵更易压缩。

### 有损压缩：目的与底层原理

- 目的：
  - 在可接受的主观质量下尽可能减小体积。
  - 依据人眼视觉系统（HVS）移除难以察觉的信息。
  - 通过率失真优化（RDO）平衡码率（体积）与失真（质量）。

- 感知驱动与颜色空间：
  - RGB → YCbCr/YCgCo/YUV：将亮度（Y/ luma）与色度（Cb/Cr / chroma）分离，贴近人眼敏感性。
  - 色度采样（chroma subsampling）：4:4:4、4:2:2、4:2:0 等，降低色度分辨率来减码率，对视觉影响较小。
- 分块预测与变换编码（block-based transform coding）：
  - JPEG：8×8 DCT（离散余弦变换），DC 差分、AC 之“Z 字形扫描（zig‑zag）+ RLE（游程编码）”。
  - WebP（有损，VP8 intra）：块内预测（intra prediction）+ 4×4/16×16 DCT/副变换，布尔编码器（bool coder）概率模型。
  - AVIF（AV1 intra）：多尺寸块划分（到 128×128 超块）、多种变换（DCT/ADST/Identity）、丰富的方向预测。
- 量化（quantization，决定“丢多少”）：
  - 将频域系数按表缩放取整，去除细微高频（纹理/噪声）细节。
  - 质量参数（quality/QP）：实质控制量化步长大小（越低越小，失真越大）。
- 熵编码与率失真优化（R-D optimization）：
  - 熵编码：Huffman/算术/区间编码结合自适应概率模型。
  - RDO：在“码率（bits）与失真（distortion，如 MSE/SSIM）”间取最优；编码器以 λ（拉格朗日乘子）评估候选模式。
- 回环滤波（in-loop filters）与伪影：
  - JPEG 无回环滤波，易见“块状（blocking）/振铃（ringing）/色带（banding）”。
  - AV1/VP8 提供去块（deblocking）、CDEF/环路复原（loop restoration）等减少块边界与振铃伪影。
- 感知指标：
  - PSNR、SSIM/MS‑SSIM、VMAF：用以衡量主观质量的代理。实际选型仍需主观比对。

与本项目实现的对应：

- `image_extreme`：采用 WebP 有损路径，编码前可对大图等比例缩放以帮助达成 `max_size_kb`；编码中按质量序列递减（80→70→…→1）直至达到目标体积或最低质量。
- `image_ultra`：当 `quality>=95` 走无损，否则走有损；可视为简单的“感知阈值”分流。
- `quality`：映射到有损量化强度；`method` 控制编码器努力程度（搜索/模式选择更充分）。
- GIF 动画：在有损路径下转成 WebP 动画（帧内有损编码），保持时序信息。

术语补充：

- DCT/ADST：用于能量集中与去相关的正交变换，ADST 对边界信号更友好。
- 量化表（quantization table）：为不同频带分配不同量化步长的矩阵。
- Z 字形扫描（zig‑zag scan）：按低频到高频次序线性化块系数，利于 RLE 与熵编码。
- 伪影（artifact）：失真可见的副作用，如块状、振铃、色带、蚊噪（mosquito noise）。
- RDO（rate‑distortion optimization）：在比特开销与失真代价间取最优决策。

### 选择建议（经验值）

- 图标/插画/线稿/带透明：优先无损（`image_lossless` 或 `image_force_lossless`），或使用 WebP 无损；若需极小体积且允许轻微失真，可用 `image_extreme`。
- 摄影/复杂纹理：优先有损（WebP/AVIF）。在相同视觉质量下，AVIF 体积通常更小；若兼容性优先，可选 WebP。
- 动图（GIF）：转换为 WebP 动画体积更小、质量更好。本项目已在有损/无损路径下对 GIF→WebP 动画做了处理。
- 分辨率：允许缩放时更易达到目标体积；`keep_original_size=false` 会在有损模式下对超大图做等比例缩放（默认阈值 1200px 边）。

## API接口

### 1. 获取压缩类型信息

**接口地址:** `GET /api/image/compression-types`

**功能:** 获取所有支持的压缩类型、参数说明和格式信息

**响应示例:**

```json
{
  "compression_types": {
    "image_lossless": {
      "name": "通用图片无损压缩",
      "description": "支持所有常用格式的无损压缩，保持透明度",
      "parameters": ["max_size_kb"],
      "output_format": "webp",
      "supports_transparency": true,
      "supported_formats": [".png", ".jpg", ".jpeg", ".bmp", ".tiff", ".tif", ".gif"],
      "category": "universal"
    },
    "image_extreme": {
      "name": "通用图片极度压缩",
      "description": "支持所有常用格式的有损压缩，可选择是否缩放",
      "parameters": ["max_size_kb", "keep_original_size"],
      "output_format": "webp",
      "supports_transparency": true,
      "supports_animation": true,
      "supported_formats": [".png", ".jpg", ".jpeg", ".bmp", ".tiff", ".tif", ".gif"],
      "category": "universal"
    },
    "image_force_lossless": {
      "name": "通用图片强制无损压缩",
      "description": "支持所有常用格式的强制无损压缩，忽略大小限制",
      "parameters": [],
      "output_format": "webp",
      "supports_transparency": true,
      "supported_formats": [".png", ".jpg", ".jpeg", ".bmp", ".tiff", ".tif", ".gif"],
      "category": "universal"
    },
    "image_ultra": {
      "name": "通用图片超强压缩",
      "description": "支持所有常用格式的超强压缩，自动根据质量选择有损/无损",
      "parameters": ["max_size_kb", "quality", "keep_original_size"],
      "output_format": "webp",
      "supports_transparency": true,
      "supports_animation": true,
      "supported_formats": [".png", ".jpg", ".jpeg", ".bmp", ".tiff", ".tif", ".gif"],
      "category": "universal"
    },
    "webp": {
      "name": "WebP格式转换",
      "description": "转换为WebP格式，支持透明度和动画",
      "parameters": ["quality", "optimize", "method"],
      "output_format": "webp",
      "supports_transparency": true,
      "supports_animation": true,
      "supported_formats": [".png", ".jpg", ".jpeg", ".bmp", ".tiff", ".tif", ".gif"],
      "category": "format_conversion"
    },
    "avif": {
      "name": "AVIF格式转换",
      "description": "转换为AVIF格式，更好的压缩效果",
      "parameters": [],
      "output_format": "avif",
      "supports_transparency": true,
      "supports_animation": false,
      "supported_formats": [".png", ".jpg", ".jpeg", ".bmp", ".tiff", ".tif", ".gif"],
      "category": "format_conversion"
    }
  },
  "supported_input_formats": [".png", ".jpg", ".jpeg", ".bmp", ".tiff", ".tif", ".gif"],
  "parameters": {
    "max_size_kb": {
      "description": "目标最大文件大小（KB）",
      "type": "integer",
      "default": 50,
      "range": "1-10000"
    },
    "quality": {
      "description": "压缩质量（WebP/AVIF）",
      "type": "integer",
      "default": 80,
      "range": "0-100"
    },
    "keep_original_size": {
      "description": "是否保持原始尺寸（不缩放）",
      "type": "boolean",
      "default": false
    },
    "optimize": {
      "description": "是否启用优化",
      "type": "boolean",
      "default": true
    },
    "method": {
      "description": "压缩方法（0-6，6为最强压缩）",
      "type": "integer",
      "default": 6,
      "range": "0-6"
    }
  }
}
```

### 2. 图片压缩接口

**接口地址:** `POST /api/image/compress`

**功能:** 上传ZIP压缩包进行图片压缩，返回压缩后的ZIP文件

**请求参数:**

- `file`: ZIP文件（必需）- 包含要压缩的图片文件
- `compression_type`: 压缩类型（必需）
  
  通用图片压缩（支持所有格式）:
  - `image_lossless`: 通用图片无损压缩
  - `image_extreme`: 通用图片极度压缩（有损）
  - `image_force_lossless`: 通用图片强制无损压缩
  - `image_ultra`: 通用图片超强压缩（智能有损/无损）
  
  格式转换:
  - `webp`: 转换为WebP格式
  - `avif`: 转换为AVIF格式
- `max_size_kb`: 目标最大文件大小(KB)，默认50
- `quality`: WebP/AVIF质量 (0-100)，默认80
  - 说明：当前 AVIF 转换为固定高质量，`quality` 仅对 WebP 相关流程生效
- `keep_original_size`: 是否保持原始尺寸，默认False
- `optimize`: 是否启用优化，默认True
- `method`: 压缩方法 (0-6)，默认6

**响应内容:**

- Body 类型: `application/zip`（二进制流）。
- 内容结构: 将输入 ZIP 中发现的支持图片按所选策略压缩后，按原目录结构打包成 ZIP 并返回。
- 文件命名: 保留原文件名，扩展名按输出格式替换为 `.webp` 或 `.avif`。
  - `image_*` 与 `webp` 类型输出 `.webp`；`avif` 类型输出 `.avif`。
- 动画/透明:
  - 动画 GIF 在 `image_*` 与 `webp` 类型下转换为 WebP 动画；`avif` 类型不支持动画，仅取第一帧。
  - PNG/GIF 等透明度在 WebP/AVIF 输出中保留。
- 非图片文件:
  - `webp`/`avif` 转换类型会将非图片文件原样复制到输出 ZIP；
  - `image_*` 压缩类型仅输出处理后的图片文件（非图片不包含在输出 ZIP）。
- 目录结构: 保留输入 ZIP 内原有的相对目录层级。

**响应头:**

- `Content-Type`: `application/zip`
- `Content-Disposition`: 附件下载文件名（包含 `compressed_<type>_YYYYMMDD_HHMMSS.zip`）
- `X-Compression-Type`: 使用的压缩类型
- `X-Original-Size-KB`: 上传ZIP包大小（KB）
- `X-Compressed-Size-KB`: 输出ZIP包大小（KB）
- `X-Compression-Ratio`: 压缩率百分比（基于ZIP大小，保留1位小数）
- `X-Processed-Files`: 处理的文件数量

说明：`X-Compression-Ratio = (1 - 压缩后ZIP大小 / 原始ZIP大小) * 100`。

成功响应示例（部分响应头）:

```http
HTTP/1.1 200 OK
Content-Type: application/zip
Content-Disposition: attachment; filename="compressed_image_extreme_20241031_113000.zip"
X-Compression-Type: image_extreme
X-Original-Size-KB: 1520.5
X-Compressed-Size-KB: 240.8
X-Compression-Ratio: 84.2
X-Processed-Files: 37
```

错误响应:

- 400（请求不合法）

```json
{ "detail": "文件必须是ZIP压缩包格式" }
```

```json
{ "detail": "ZIP文件中没有找到支持的图片文件" }
```

- 500（服务器内部错误）

```json
{ "detail": "图片压缩失败: <错误信息>" }
```

## 压缩类型详解

### 通用图片强制无损压缩 (image_force_lossless)

- 用途: 忽略目标大小强制无损压缩
- 输出格式: WebP
- 透明/动画: 透明度保留；动画 GIF 转为 WebP 动画
- 参数及默认值: 无
- 压缩细节:
  - 始终使用 WebP 无损（`lossless=True`, `optimize=True`, `method=6`）。
  - 不缩放尺寸，不校验 `max_size_kb`。
  - 动画 GIF 使用无损（`quality=100`, `lossless=True`）转 WebP 动画。
- 支持格式: PNG, JPG, JPEG, BMP, TIFF, GIF

### 通用图片无损压缩 (image_lossless)

- 用途: 适用于所有格式的无损压缩
- 输出格式: WebP
- 透明/动画: 透明度保留；动画 GIF 转为 WebP 动画
- 参数及默认值: `max_size_kb=50`
- 压缩细节:
  - 始终使用 WebP 无损（`lossless=True`, `optimize=True`, `method=6`）。
  - 不缩放尺寸（保持原分辨率）。
  - `max_size_kb` 仅用于结果提示，不会为达成该数值而降低画质或缩小分辨率。
  - 动画 GIF 通过逐帧写入生成 WebP 动画（保留 `duration`/`loop`）。
- 支持格式: PNG, JPG, JPEG, BMP, TIFF, GIF

### 通用图片极度压缩 (image_extreme)

- 用途: 追求最小体积的有损压缩
- 输出格式: WebP
- 透明/动画: 透明度保留；动画 GIF 转为 WebP 动画
- 参数及默认值: `max_size_kb=50`, `keep_original_size=false`
- 压缩细节:
  - 静态图按质量序列自适应尝试：`[80,70,60,50,40,30,20,10,5,3,1]`，直到文件≤`max_size_kb` 或降至 1。
  - 允许缩放时，大边>1200 会按比例缩放至最长边 1200（`LANCZOS`），否则保持原尺寸。
  - 始终使用 `optimize=True`, `method=6`。
  - 动画 GIF 直接以 `quality=80` 转为 WebP 动画（不做多次质量迭代）。
- 支持格式: PNG, JPG, JPEG, BMP, TIFF, GIF

### 通用图片超强压缩 (image_ultra)

- 用途: 智能压缩，按质量阈值决定无损/有损
- 输出格式: WebP
- 透明/动画: 透明度保留；动画 GIF 转为 WebP 动画
- 参数及默认值: `max_size_kb=50`, `quality=80`, `keep_original_size=false`
- 压缩细节:
  - 当 `quality>=95` 走无损路径（`lossless=True`），否则走有损路径。
  - 无损路径: 不缩放，保持尺寸；动画 GIF 以 `quality=100` 无损写 WebP 动画。
  - 有损路径: 与 `image_extreme` 相同的自适应质量序列和可选缩放策略；动画 GIF 以 `quality=80` 转 WebP 动画。
  - 注意: 该模式中 `quality` 主要用于“选择无损/有损”，有损时内部仍按固定质量序列自适应，而非使用传入 `quality` 作为最终质量。
- 支持格式: PNG, JPG, JPEG, BMP, TIFF, GIF

### WebP格式转换 (webp)

- 用途: 标准 WebP 格式转换（不按目标体积迭代）
- 输出格式: WebP
- 透明/动画: 透明度保留；动画 GIF 转为 WebP 动画
- 参数及默认值: `quality=80`, `optimize=true`, `method=6`
- 压缩细节:
  - `quality>=95` 时采用 WebP 无损；否则走有损。
  - 不缩放尺寸，不按体积目标迭代质量。
  - 动画 GIF 使用传入的 `quality/optimize/method` 写为 WebP 动画，保留 `duration`/`loop`。
- 支持格式: PNG, JPG, JPEG, BMP, TIFF, GIF

### AVIF格式转换 (avif)

- 用途: 转为 AVIF（更高压缩效率）
- 输出格式: AVIF
- 透明/动画: 透明度保留；动画不支持（GIF 仅取第一帧）
- 参数及默认值: 无（内部固定 `quality=100`, `speed=0`）
- 压缩细节:
  - 不缩放尺寸，不按体积目标迭代质量。
  - 动画 GIF 仅取第一帧并转换（提示日志中会标注）。
- 支持格式: PNG, JPG, JPEG, BMP, TIFF, GIF

### 格式预处理细节（与实现一致）

- JPEG: 若为灰度 `L` 或彩色 `RGB` 保持原模式；其他模式转换为 `RGB`。
- PNG: 若为 `RGBA/LA` 直接保留透明；`P` 模式含透明时转 `RGBA`，否则转 `RGB`。
- GIF: 动画 GIF 在对应流程中转为 WebP 动画；静态 GIF 的 `P` 模式含透明时转 `RGBA`，否则转 `RGB`。
- BMP/TIFF: 如含透明（`RGBA/LA`）则保留；否则按 `RGB`/`L` 保持或转换为 `RGB`。

## 参数与概念映射（理解压缩行为）

- `compression_type`
  - `image_lossless`/`image_force_lossless`：不丢失像素信息（WebP 无损），适合 UI/图标/透明素材。
  - `image_extreme`：有损并可缩放，逐步降低 `quality` 并尝试达到 `max_size_kb`，追求极小体积。
  - `image_ultra`：智能模式，`quality>=95` 走无损，否则走有损。
  - `webp`/`avif`：仅做格式转换（不按目标体积迭代质量）。
- `quality`：量化强度的直觉控制，越低体积越小但细节越少。对 WebP 生效；当前 AVIF 转换固定高质量。
- `max_size_kb`：目标上限（KB）。`image_extreme` 等会迭代尝试 `quality` 并（在允许时）缩放以满足目标。
- `keep_original_size`：保持原分辨率。关闭时（有损模式）大图会按阈值做等比例缩放以降低体积。
- `optimize`/`method`：WebP 编码器优化与方法等级（0-6），数值越高通常越慢但压缩率更好。

## 实战建议

- 追求极小体积：`image_extreme`，设置合适的 `max_size_kb`，可允许缩放以更易达标。
- 保真与透明优先：`image_lossless` 或 `image_force_lossless`。
- 平衡质量/体积：`image_ultra`，以 `quality` 粗调，有需要时再用 `max_size_kb` 控体积。
- 格式选择：优先 WebP 做通用落地；对前沿平台/更高压缩比可选 AVIF（注意编码速度与兼容性）。

## 使用示例

### curl 示例

```bash
# 获取压缩类型信息
curl -X GET "http://localhost:8000/api/image/compression-types"

# 通用图片无损压缩（支持所有格式）
curl -X POST "http://localhost:8000/api/image/compress" \
  -F "file=@images.zip" \
  -F "compression_type=image_lossless" \
  -F "max_size_kb=200" \
  --output compressed_images.zip

# 通用图片极度压缩（有损压缩）
curl -X POST "http://localhost:8000/api/image/compress" \
  -F "file=@images.zip" \
  -F "compression_type=image_extreme" \
  -F "max_size_kb=50" \
  -F "keep_original_size=false" \
  --output compressed_images.zip

# 通用超强压缩（智能压缩）
curl -X POST "http://localhost:8000/api/image/compress" \
  -F "file=@images.zip" \
  -F "compression_type=image_ultra" \
  -F "max_size_kb=50" \
  -F "quality=85" \
  -F "keep_original_size=false" \
  --output compressed_images.zip
```

### Python 示例

```python
import requests

# 压缩图片 - 使用新的通用极度压缩（推荐）
with open('images.zip', 'rb') as f:
    files = {'file': f}
    data = {
        'compression_type': 'image_extreme',  # 支持所有格式
        'max_size_kb': 50,
        'keep_original_size': False
    }
    
    response = requests.post(
        'http://localhost:8000/api/image/compress',
        files=files,
        data=data
    )
    
    if response.status_code == 200:
        with open('compressed.zip', 'wb') as output:
            output.write(response.content)
        print("压缩完成!")
```

## 注意事项

1. **输入格式:** 必须是ZIP压缩包格式
2. **支持的图片:** PNG, JPG, JPEG, BMP, TIFF, GIF
3. **输出格式:** 根据压缩类型输出WebP或AVIF格式
4. **透明度:** PNG透明度在所有压缩模式下都会保留
5. **目录结构:** 压缩后会保持原有的目录结构
6. **临时文件:** 处理过程中使用临时目录，自动清理
7. **AVIF质量:** 当前 AVIF 转换固定为高质量，`quality` 参数对 AVIF 不生效
