# 图片格式转换

> 使用 fmt 参数指定图片的输出格式。

## 参数说明

| 参数    | 含义       | 说明                                       |
| :---- | -------- | ---------------------------------------- |
| `fmt` | **输出格式** | 不指定时通常保持源格式；HEIC、相机 RAW 等输出 JPEG。别名：`fm` |

可识别的输入格式见 [支持格式](/formats)。

## 输出格式

### 图片格式

| fmt 值           | 格式        | 特点                  |  透明 |  动图 |
| :-------------- | --------- | ------------------- | :-: | :-: |
| `jpg` / `jpeg`  | JPEG      | 兼容性最好，适合照片          |  –  |  –  |
| `png`           | PNG       | 无损，体积较大             |  ✓  |  ✓  |
| `tpng`          | PNG（量化压缩） | 减色压缩，体积明显小于普通 PNG   |  ✓  |  –  |
| `webp`          | WebP      | 质量与体积均衡，现代浏览器普遍支持   |  ✓  |  ✓  |
| `avif`          | AVIF      | 压缩率高，支持 HDR         |  ✓  |  ✓  |
| `jxl`           | JPEG XL   | 压缩率高，支持 HDR 与高位深    |  ✓  |  –  |
| `heic` / `heif` | HEIC      | 苹果生态常用，支持 HDR       |  ✓  |  –  |
| `gif`           | GIF       | 兼容性最好的动图格式，至多 256 色 |  ✓  |  ✓  |
| `tiff`          | TIFF      | 专业场景使用              |  ✓  |  –  |
| `bmp`           | BMP       | 无压缩位图               |  –  |  –  |

### 自动与保持

| fmt 值  | 行为                                              |
| :----- | ----------------------------------------------- |
| `auto` | **按浏览器自动选择**：依次尝试 JPEG XL、AVIF、WebP，都不支持时按源格式输出 |
| `keep` | **保持源格式**。源为 SVG 时会自动过滤危险代码                     |

`fmt=auto` 根据请求的 `Accept` 头判断浏览器支持的格式，响应带 `Vary: Accept`。动图不会输出为 JPEG XL，会在 AVIF 与 WebP 中选择。也可写作 `auto=format`。

> **Note**
>
> 显式指定 `fmt=avif` 或 `fmt=webp` 而浏览器不支持时，系统同样会自动降级：AVIF 降为 WebP，WebP 降为源格式的默认输出。

### 信息输出

以下取值返回文本或 JSON，而不是图片：

| fmt 值       | 返回内容                                                      |
| :---------- | --------------------------------------------------------- |
| `info`      | 图片元数据（JSON）                                               |
| `color`     | 图片主色                                                      |
| `blurhash`  | [BlurHash](/bitiful-s4/features/hash-placeholder) 占位符字符串  |
| `thumbhash` | [ThumbHash](/bitiful-s4/features/hash-placeholder) 占位符字符串 |

调色板、感知哈希、人脸、标签等更多分析输出见 [图片分析](/coreix/features/analysis)。

## 效果演示

原始图像：

![原图](https://demo.bitiful.com/girl.jpeg?rect=0,0,1000,1000\&w=300\&q=90)

转换为 WebP：[https://demo.bitiful.com/girl.jpeg?rect=0,0,1000,1000\&w=300 **`&fmt=webp`**](https://demo.bitiful.com/girl.jpeg?rect=0,0,1000,1000\&w=300\&fmt=webp)

![WebP 输出](https://demo.bitiful.com/girl.jpeg?rect=0,0,1000,1000\&w=300\&fmt=webp)

转换为 PNG（无损）：[https://demo.bitiful.com/girl.jpeg?rect=0,0,1000,1000\&w=300 **`&fmt=png`**](https://demo.bitiful.com/girl.jpeg?rect=0,0,1000,1000\&w=300\&fmt=png)

![PNG 输出](https://demo.bitiful.com/girl.jpeg?rect=0,0,1000,1000\&w=300\&fmt=png)

转换为 AVIF（高压缩率）：[https://demo.bitiful.com/girl.jpeg?rect=0,0,1000,1000\&w=300 **`&fmt=avif`**](https://demo.bitiful.com/girl.jpeg?rect=0,0,1000,1000\&w=300\&fmt=avif)

![AVIF 输出](https://demo.bitiful.com/girl.jpeg?rect=0,0,1000,1000\&w=300\&fmt=avif)

## 格式选择指南

| 场景              | 推荐                              |
| :-------------- | ------------------------------- |
| 网页图片，希望自动取得最小体积 | `fmt=auto`                      |
| 照片，需要最广泛的兼容性    | `jpg`                           |
| 需要透明或无损         | `png`；体积敏感时用 `tpng` 或 `webp`    |
| 追求压缩率           | `avif`                          |
| HDR 内容          | `jpg`（兼容 SDR 设备）或 `avif`        |
| 动图              | `webp` 或 `avif`；需要最广兼容性时用 `gif` |

## 使用提示

- 配合 `q`（质量）参数可进一步控制体积，默认质量为 88。
- 颜色不超过 256 种的图标、截图、线稿类图片，输出 PNG、WebP 时会自动采用无损的调色板编码，体积更小且不失真。
