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。