转换

在各种格式之间转换图片。支持常见的网页格式，以及 HEIC、JXL、BMP、ICO、JP2、QOI 和 PSD 等专业格式。

API 端点

POST /api/v1/tools/image/convert

接受 multipart 表单数据，包含一个图片文件和一个 JSON settings 字段。

参数

参数	类型	必填	默认值	说明
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 等有损格式。

支持的输出格式

格式	类型	说明
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 图片格式

请求示例

转换为 WebP：

curl -X POST http://localhost:1349/api/v1/tools/image/convert \
  -H "Authorization: Bearer si_your-api-key" \
  -F "[email protected]" \
  -F 'settings={"format": "webp", "quality": 85}'

转换为 PNG（无损）：

curl -X POST http://localhost:1349/api/v1/tools/image/convert \
  -H "Authorization: Bearer si_your-api-key" \
  -F "[email protected]" \
  -F 'settings={"format": "png"}'

响应示例

{
  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/photo.webp",
  "originalSize": 2450000,
  "processedSize": 680000
}

注意事项

• 输出文件名的扩展名会自动更新以匹配目标格式。
• 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 等。