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으로 지정 |
동영상 압축하기
프로덕션 환경 실측: 2.5 MB짜리 10초 720p 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를 사용한 안전한 재시도 방법을 설명합니다.웹훅: 작업 완료 시 알림 받기HTTPS 엔드포인트를 processing.completed와 processing.failed에 구독하고, HMAC-SHA256 서명을 검증하고, 재시도를 처리하는 방법을 설명합니다.