REST API: compress video from your own code

The API runs the server lane: ffmpeg on our encoder, billed in encode minutes. It needs the $9 or $19 plan. Compressing in your browser on the home page is free and never uploads your video; the API always uploads, because the encoding happens on our server.

Authentication

Create a key in your account and send it on every request, either way:

curl -H "Authorization: Bearer sk_your_key" https://videocompressor.tools/api/job/JOB_ID
curl -H "x-api-key: sk_your_key" https://videocompressor.tools/api/job/JOB_ID

A missing, wrong or revoked key gets 401.

Start a job

POST /api/v1/compress with a multipart form.

Field	Required	Meaning
file	yes	MP4, MOV, WebM, MKV or M4V
codec	no	vp9 (default, WebM) or av1 ($19 plan only, MP4). HEVC is refused with 400 unsupported_codec; H.264 output is not offered and is refused with 400 codec_disabled
crf	no	Quality from 0 to 63, lower is better. Default 28
maxHeight	no	Cap the output height in pixels, 16 to 4320
targetMb	no	Target size in decimal MB; the result comes in under it

curl -X POST https://videocompressor.tools/api/v1/compress \
  -H "Authorization: Bearer sk_your_key" \
  -F "[email protected]" \
  -F "codec=vp9" \
  -F "crf=28" \
  -F "maxHeight=720"

The reply is 202:

{
  "jobId": "clx123",
  "status": "PENDING",
  "codec": "vp9",
  "minutesBilled": 2,
  "minutesRemaining": 298,
  "statusUrl": "/api/job/clx123"
}

Minutes billed are the input duration rounded up to whole minutes, never less than one. To hit an exact size, send targetMb (decimal megabytes, 1 MB = 1,000,000 bytes, for example 20). The result comes in under that size. If the target is too small for the clip, the request is refused up front with 422 target_too_small and nothing is charged, instead of returning an oversized file. When targetMb is set, crf is ignored.

Poll and download

curl -H "Authorization: Bearer sk_your_key" https://videocompressor.tools/api/job/JOB_ID
curl -L -H "Authorization: Bearer sk_your_key" -o out.webm https://videocompressor.tools/api/download/JOB_ID

ready turns true when the job is done. Results are deleted after the retention window stated on the privacy page.

Limits

• 30 requests per minute per key. Over that you get 429 with a Retry-After header, and you are not charged.
• $9 plan: files up to 4 GB, 300 encode minutes a month. $19 plan: files up to 4 GB, 1,000 encode minutes a month, AV1 output, priority queue.
• Inputs up to 4K UHD (3840x2160, either orientation). Larger frames get 422 too_many_pixels and are not charged.
• A job that needs more minutes than remain gets 429 quota_exceeded and is not charged.

Errors

Status	code	Meaning
400	unsupported_codec, codec_disabled, bad_request	Fix the request
401	unauthorized	Bad or missing key
403	plan_required, forbidden	Plan lacks API or AV1, or the account is suspended
413	too_large	File over the plan's size limit
415	unsupported_input	Not a supported video type
422	unreadable_input, too_many_pixels, target_too_small	Not a readable video, larger than 4K UHD, or a target too small for the clip. Never charged
429	rate_limited, quota_exceeded	Slow down, or out of minutes. Never charged