图片 API:压缩、调整尺寸和转换格式
在一次流水线调用中调整图片尺寸、裁剪、旋转、按质量或目标字节数压缩,并将图片转换为 JPG、PNG、WebP 或 AVIF。
简要回答
调用 POST /api/v1/pipeline/,传入 sourceKey 和步骤 {"operation":"image","pipeline":[…]},其中最多可列出 8 个操作:resize(maxWidth、maxHeight)、crop(x、y、width、height)、rotate(degrees)、compress(quality 1–100 或 targetBytes)和 convert(jpg、png、webp、avif)。对于已在“我的文档”中的图片,请使用 /documents/{documentId}/process/ 并传入 {"operation":"image","pipeline":[…]}。
为网页压缩图片
典型的产品图流水线会限制尺寸并转换为 WebP。在我们的测试中,一张 224 KB 的 PNG 在约 4 秒内变成了宽 400 px、大小 30 KB 的 WebP。
curl -X POST 'https://maxscanner.app/api/v1/pipeline/' \
-H "Authorization: Bearer $MAXSCANNER_API_KEY" \
-H 'Content-Type: application/json' \
-d '{ "sourceKey": "users/<id>/media/inbox/…-photo.png", "steps": [ { "operation": "image", "pipeline": [ { "operation": "resize", "maxWidth": 1600 }, { "operation": "compress", "quality": 75, "format": "webp" } ] } ] }'达到指定的文件大小
上传门户经常要求“小于 200 KB”。请使用带 targetBytes 的 compress,而不是 quality;Worker 会搜索能满足要求的最高质量。目标值必须介于 API 允许的最小值和最大值之间(最大 20 MB)。
{ "operation": "image", "pipeline": [ { "operation": "resize", "maxWidth": 1200 }, { "operation": "compress", "targetBytes": 204800, "format": "jpg" } ] }将图片步骤与 PDF 和 OCR 串联
流水线可以在图片步骤之后继续:添加 {"operation":"convert","format":"pdf"} 将结果封装为 PDF,或添加 {"operation":"ocr","format":"pdf"} 使其可搜索。当下一步需要时,图片步骤会自动输出 PNG。
常见问题
压缩会去除元数据吗?
重新编码的图片不会保留 GPS 位置等 EXIF 数据,对于公开图片来说,这通常正是你想要的。
应该选择哪种格式?
网站用 WebP;最看重兼容性时用 JPG;截图和线条图用 PNG;如果你的受众使用现代浏览器,用 AVIF 可以得到最小的文件。