API
媒體 API:影片和音訊轉換
透過媒體端點對影片進行壓縮、轉換、剪輯、調整大小、靜音以及轉為 GIF,並轉換或壓縮音訊。
簡要回答
先透過直接上傳上傳檔案,然後呼叫 POST /api/v1/media/process/,將 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)和目標格式。輪詢傳回的工作即可。上傳的單一檔案限制為 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;duration 用於設定 GIF 長度 |
壓縮影片
正式環境中的實測結果:一個 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/:它會回報媒體 Worker 是否可用
常見問題
我能處理的最大影片是多少?
目前每次上傳最大 50 MB。媒體 Worker 本身最多可接受 500 MB,如果你需要處理更大的檔案,請聯絡支援團隊。
壓縮影片時會保留音訊嗎?
會,以 AAC 格式保留,除非你使用 mute-video。