API
メディア API:動画と音声の変換
メディアエンドポイントで、動画の圧縮、変換、トリミング、リサイズ、ミュート、GIF 化と、音声の変換や圧縮を行えます。
要点
直接アップロードでファイルをアップロードし、objectKey を sourceKey として、operation(convert、compress-video、compress-audio、trim-video、trim-audio、resize-video、change-video-speed、mute-video、video-to-gif、gif-to-mp4)と変換先の format を指定して POST /api/v1/media/process/ を送信します。返されたジョブをポーリングしてください。アップロードはファイルあたり 50 MB までです。
操作とオプション
入力:MP4、MOV、MKV、AVI、WebM、MP3、WAV、M4A、FLAC、OGG、AAC、GIF。
| operation | 主なフィールド |
|---|---|
| convert | format: mp4, webm, mkv, mp3, wav, flac, m4a, ogg, aac, gif |
| compress-video | crf(18〜40、値が大きいほどファイルは小さくなる)、またはサイズ目標を指定する targetMb |
| compress-audio | bitrate(例:"128k") |
| trim-video / trim-audio | start と duration(秒単位) |
| resize-video / change-video-resolution | width, height |
| change-video-speed | speed(例:1.5) |
| mute-video, video-to-gif, gif-to-mp4 | format。GIF の長さは duration で指定 |
動画を圧縮する
本番環境での実測:10 秒、720p、2.5 MB の MP4 が、約 19 秒で 1.6 MB の H.264/AAC ファイルになりました。長い動画やビットレートの高い動画では、それに比例して時間がかかります。
curl -X POST 'https://maxscanner.app/api/v1/media/process/' \
-H "Authorization: Bearer $MAXSCANNER_API_KEY" \
-H 'Content-Type: application/json' \
-d '{ "operation": "compress-video", "sourceKey": "users/<id>/media/inbox/…-clip.mp4", "filename": "clip.mp4", "format": "mp4" }'実践的なアドバイス
- メディアジョブのポーリング間隔は長め(10 秒ごと)にし、長い動画には数分の余裕を見てください
- 出力は MP4 がおすすめです。どこでも再生でき、この API では速度優先でエンコードされる WebM より通常は小さくなります
- 時間を節約するため、圧縮の前にトリミングします
- 大量のバッチを処理する前に GET /api/v1/media/health/ を確認してください。メディアワーカーが利用可能かどうかがわかります
よくある質問
処理できる動画の最大サイズはどれくらいですか?
現在はアップロードあたり 50 MB です。メディアワーカー自体は最大 500 MB まで受け付けるため、より大きなファイルが必要な場合はサポートにお問い合わせください。
動画を圧縮しても音声は残りますか?
はい。mute-video を使わない限り、AAC として残ります。
関連ガイド
ファイル:URL からのインポートと直接アップロード公開 URL または署名付きの直接アップロードでファイルを MaxScanner に取り込む方法と、それぞれの上限、返される ID を説明します。ジョブ、ポーリング、再試行、冪等性非同期ジョブの状態の遷移、リクエストを無駄にしないポーリングの方法、Idempotency-Key を使った安全な再試行について説明します。Webhook:ジョブの完了時に通知を受け取るHTTPS エンドポイントを processing.completed と processing.failed にサブスクライブし、HMAC-SHA256 署名を検証して、再試行に対処する方法を説明します。