mirror of
https://github.com/snapotter-hq/SnapOtter.git
synced 2026-08-03 07:46:42 +02:00
SnapOtterandGitHub
4963ab3bbd
All 181 docs markdown files translated into 20 languages (apps/docs/<locale>/**). Companion to the i18n code PR; admin-merged because the file count exceeds GitHub's per-PR CI trigger limit. Validated by pnpm i18n:check (all surfaces, 0 stale/missing) and a clean all-locale docs build.
85 lines
2.9 KiB
Markdown
85 lines
2.9 KiB
Markdown
---
|
||
description: "在各种格式之间转换图片，包括 AVIF、JXL 和 HEIC 等现代格式。"
|
||
i18n_source_hash: 562f8270e8c3
|
||
i18n_provenance: human
|
||
i18n_output_hash: 238017f07183
|
||
---
|
||
|
||
# 转换 {#convert}
|
||
|
||
在各种格式之间转换图片。支持常见的网页格式，以及 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 等。
|