Reduce video file sizes through aggressive Constant Rate Factor (CRF) quantization, bitrate capping, resolution downscaling, and audio stripping.
Need full codec & container matrix details?
See Video Encoding for detailed FFmpeg container compatibilities, encoders, and transcode settings.
Need general upload and polling mechanics?
See File Conversion for multipart upload (POST /api/uploads), status polling, and download token authentication.
Same-Format Video Optimization
MP4 → MP4 or WebM → WebM), you must provide "jobIntent": "transform" in your request body.1. Constant Rate Factor (CRF)
Higher CRF values instruct the encoder to compress macroblocks more aggressively. Raising CRF from 23 to 28–32 typically cuts file size by 40–60% with minimal visual difference.
2. Resolution Downscaling
Downscaling a 1080p source video to 720p (resolution: "720p") drastically cuts data rate while remaining crisp on mobile devices.
3. Bitrate Capping
Setting a strict bitrate ceiling (e.g. 1500 kbps for 720p, 2500 kbps for 1080p) prevents dynamic high-motion scenes from inflating total file size.
4. Audio Optimization
Capping audio to 96 kbps or stripping unneeded audio tracks entirely (stripAudio: true) yields clean additional size reduction.
{
"fileId": "<FILE_ID>",
"toFormat": "mp4",
"jobIntent": "transform",
"options": {
"codec": "h264",
"crf": 30,
"bitrate": 1500,
"resolution": "720p",
"audioBitrate": 96
}
}| Parameter | Type | Required | Description |
|---|---|---|---|
| fileId | string | Yes | The storage key returned by POST /api/uploads. |
| toFormat | string | Yes | Target video container ('mp4' or 'webm'). Accepted: "mp4" | "webm" |
| jobIntent | string | Yes | Must be set to 'transform' for same-format compression. Accepted: "transform" |
| options.crf | integer | No | Constant Rate Factor (0–51). Use 28–32 for high compression. Accepted: 0 – 51 |
| options.bitrate | integer | No | Maximum video bitrate cap in kbps. Accepted: 100 – 100,000 |
| options.resolution | string | No | Target vertical height. Aspect ratio is preserved automatically. Accepted: "720p" | "1080p" |
| options.codec | string | No | Video encoder ('h264'). Leave it unset to use the target container's own default — WebM writes VP8. Accepted: "h264" |
| options.audioBitrate | integer | No | Audio bitrate in kbps (e.g. 96 or 128 kbps). Accepted: 8 – 512 |
| options.stripAudio | boolean | No | Strips all audio streams from output video. Accepted: true | false |
| HTTP | Error Code | Cause & Resolution |
|---|---|---|
| 400 | SAME_FORMAT_NOOP | Omitted jobIntent: 'transform' when compressing to same format (e.g. mp4 -> mp4). |
| 400 | INVALID_OPTIONS | Codec is incompatible with container (e.g. h264 with webm). |
| 413 | FILE_TOO_LARGE | Video file exceeds upload size limit (Guest: 25 MB, Free: 100 MB, Pro: 2 GB, Business: 5 GB). |
| 503 | STORAGE_WARNING_HEAVY | Server storage under pressure; heavy video compression temporarily throttled. |
# Compress an MP4 video file in place
curl -X POST "https://api.orbconvert.com/api/conversions" \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"fileId": "<FILE_ID>",
"toFormat": "mp4",
"jobIntent": "transform",
"options": {
"codec": "h264",
"crf": 30,
"bitrate": 1500,
"resolution": "720p"
}
}'Was this page helpful?