画像 API:圧縮、リサイズ、変換
1 回のパイプライン呼び出しで、画像のリサイズ、切り抜き、回転、画質またはバイト数を目標にした圧縮、JPG・PNG・WebP・AVIF への変換を行えます。
要点
sourceKey と、最大 8 つの操作を並べたステップ {"operation":"image","pipeline":[…]} を指定して POST /api/v1/pipeline/ を送信します。操作は resize(maxWidth、maxHeight)、crop(x、y、width、height)、rotate(degrees)、compress(quality 1〜100 または targetBytes)、convert(jpg、png、webp、avif)です。マイドキュメントにある画像には、{"operation":"image","pipeline":[…]} を指定して /documents/{documentId}/process/ を使います。
Web 向けに圧縮する
一般的な商品写真のパイプラインでは、サイズに上限を設けたうえで 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 未満」といった条件がよくあります。その場合は quality ではなく targetBytes を指定して compress を使ってください。ワーカーが、目標に収まる最も高い画質を探します。目標値は、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 データは残りません。公開する画像では、通常これが望ましい動作です。
どの形式を選べばよいですか?
Web サイトには WebP、互換性を最優先する場合は JPG、スクリーンショットや線画には PNG、閲覧者がモダンブラウザーを使っていてファイルを最小にしたい場合は AVIF が適しています。