2026-07-11 13:52:47 +08:00
|
|
|
|
---
|
|
|
|
|
|
description: "在各种格式之间转换图片，包括 AVIF、JXL 和 HEIC 等现代格式。"
|
2026-07-15 21:55:51 +08:00
|
|
|
|
i18n_source_hash: 2639f333073f
|
2026-07-11 13:52:47 +08:00
|
|
|
|
i18n_provenance: human
|
|
|
|
|
|
i18n_output_hash: 238017f07183
|
|
|
|
|
|
---
|
|
|
|
|
|
|
2026-07-15 21:55:51 +08:00
|
|
|
|
# 转换图片 {#convert}
|
2026-07-11 13:52:47 +08:00
|
|
|
|
|
|
|
|
|
|
在各种格式之间转换图片。支持常见的网页格式，以及 HEIC、JXL、BMP、ICO、JP2、QOI 和 PSD 等专业格式。
|
|
|
|
|
|
|
|
|
|
|
|
## API 端点 {#api-endpoint}
|
|
|
|
|
|
|
|
|
|
|
|
`POST /api/v1/tools/image/convert`
|
|
|
|
|
|
|
|
|
|
|
|
接受 multipart 表单数据，包含一个图片文件和一个 JSON `settings` 字段。
|
|
|
|
|
|
|
|
|
|
|
|
## 参数 {#parameters}
|
|
|
|
|
|
|
|
|
|
|
|
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
|
|
|
|
|
|-----------|------|----------|---------|-------------|
|
|
|
|
|
|
| format | string | 是 | - | 目标格式：`jpg`、`png`、`webp`、`avif`、`tiff`、`gif`、`heic`、`heif`、`jxl`、`bmp`、`ico`、`jp2`、`qoi`、`psd`、`ppm`、`eps`、`tga` |
|
|
|
|
|
|
| quality | number | 否 | - | 输出质量（1-100）。适用于 jpg、webp、avif、heic 等有损格式。 |
|
|
|
|
|
|
|
|
|
|
|
|
## 支持的输出格式 {#supported-output-formats}
|
|
|
|
|
|
|
|
|
|
|
|
| 格式 | 类型 | 说明 |
|
|
|
|
|
|
|--------|------|-------|
|
|
|
|
|
|
| jpg | 有损 | JPEG，兼容性最佳 |
|
|
|
|
|
|
| png | 无损 | 支持透明 |
|
|
|
|
|
|
| webp | 两者 | 现代网页格式，压缩效果好 |
|
|
|
|
|
|
| avif | 有损 | 下一代格式，压缩效果极佳 |
|
|
|
|
|
|
| tiff | 两者 | 印刷/出版工作流 |
|
|
|
|
|
|
| gif | 无损 | 限于 256 种颜色 |
|
|
|
|
|
|
| heic / heif | 有损 | Apple 生态系统格式 |
|
|
|
|
|
|
| jxl | 两者 | JPEG XL，下一代格式 |
|
|
|
|
|
|
| bmp | 无损 | 未压缩位图 |
|
|
|
|
|
|
| ico | 无损 | Windows 图标格式 |
|
|
|
|
|
|
| jp2 | 有损 | JPEG 2000 |
|
|
|
|
|
|
| qoi | 无损 | Quite OK Image 格式 |
|
|
|
|
|
|
| psd | 分层 | Adobe Photoshop（需要 ImageMagick） |
|
|
|
|
|
|
| ppm | 无损 | Portable Pixmap（PPM/PGM/PBM） |
|
|
|
|
|
|
| eps | 矢量 | Encapsulated PostScript |
|
|
|
|
|
|
| tga | 无损 | Targa 图片格式 |
|
|
|
|
|
|
|
|
|
|
|
|
## 请求示例 {#example-request}
|
|
|
|
|
|
|
|
|
|
|
|
转换为 WebP：
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST http://localhost:1349/api/v1/tools/image/convert \
|
|
|
|
|
|
-H "Authorization: Bearer si_your-api-key" \
|
|
|
|
|
|
-F "file=@photo.jpg" \
|
|
|
|
|
|
-F 'settings={"format": "webp", "quality": 85}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
转换为 PNG（无损）：
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST http://localhost:1349/api/v1/tools/image/convert \
|
|
|
|
|
|
-H "Authorization: Bearer si_your-api-key" \
|
|
|
|
|
|
-F "file=@photo.jpg" \
|
|
|
|
|
|
-F 'settings={"format": "png"}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## 响应示例 {#example-response}
|
|
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
|
{
|
|
|
|
|
|
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
|
|
|
|
|
|
"downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/photo.webp",
|
|
|
|
|
|
"originalSize": 2450000,
|
|
|
|
|
|
"processedSize": 680000
|
|
|
|
|
|
}
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## 注意事项 {#notes}
|
|
|
|
|
|
|
|
|
|
|
|
- 输出文件名的扩展名会自动更新以匹配目标格式。
|
|
|
|
|
|
- SVG 输入在转换前会以 300 DPI 光栅化。
|
|
|
|
|
|
- PSD 转换需要在服务器上安装 ImageMagick。
|
|
|
|
|
|
- BMP、EPS、ICO、JP2、JXL、PPM、QOI 和 TGA 使用专门的 CLI 编码器，并绕过 Sharp 处理。
|
|
|
|
|
|
- HEIC/HEIF 编码使用系统的 HEIC 编码器库。
|
|
|
|
|
|
- 输入格式范围很广：JPEG、PNG、WebP、AVIF、TIFF、GIF、HEIC、RAW（CR2、NEF、ARW 等）、PSD、SVG、BMP 等。
|
