Developer API

Video Compression API — Exact-Size Output

Send a public video URL or upload a file. VidSmaller runs the compression asynchronously, reports progress, and returns a downloadable result.

Download OpenAPI Download Postman collection Open in Postman

Updated: Updated: 2026-10-30
Limits verified: Limits verified: 2026-10-31
Uses your VidSmaller credits: Uses your VidSmaller credits

On this page

Start in 3 steps

Create a key, submit a video, then poll the job or wait for a signed webhook.

1
Create a key
Name the key in your dashboard. Copy the API key and webhook secret when they appear; both are shown only once.
2
Create a job
Send a public URL or upload a file, then choose target_size_mb and optional codec, resolution, and format settings.
3
Get the result
Poll the job status or receive a signed webhook. Completed jobs include a short-lived authenticated download URL.

Free read-only endpoints

Platform-limit and estimate requests need no API key and allow 600 requests per hour per IP.

One compression workflow

Authenticated jobs use the same credits, file limits, codec access, and burst limits as the web compressor.

Two input options

Use a public direct video URL or request a signed upload URL for a local file.

Stable v1 contract

New fields may be added, but existing v1 fields will not change meaning.

Authentication & credits

Only compression jobs and uploads require authentication. Read-only platform and estimate endpoints are public.

Bearer API key

Create keys in the API Keys dashboard. Store the full value securely because it cannot be shown again.

Authorization: Bearer $VIDSMALLER_API_KEY

Shared credit balance

The API has no separate plan. Jobs reserve credits when created, settle against actual encoder time, and refund automatically when processing fails.

/api/v1/platforms

Returns every upload limit VidSmaller tracks, together with safe compression targets, source links, and the date each limit was verified.

GET

Returns 15 platforms. No authentication or parameters required.

curl -s https://vidsmaller.com/api/v1/platforms

Response fields

statedLimitMbnumber

The upload limit advertised by the platform for its primary tier.

safeTargetMbnumber

A slightly lower compression target that leaves room for encoder variance.

tierNotestring | null

A caveat when the advertised limit depends on account type, app, or API access.

tiers[]array

All documented free, paid, bot, or client-specific tiers and notes.

verifiedAtdate

The date a human last checked the platform's own documentation.

sources[]array

The source pages used to verify the limit.

/api/v1/estimate

Checks whether a file fits a destination and estimates the output of a compression setting. GET query fields and the POST JSON body use the same names.

GET · POSTNo API key required

curl -s "https://vidsmaller.com/api/v1/estimate?sizeMb=150.7&durationSeconds=596&platform=discord"

Request fields

sizeBytesinteger

Source file size in bytes. Required unless sizeMb is provided.

sizeMbnumber

Source size in MiB, where 1 MB equals 1,048,576 bytes.

durationSecondsnumber

Optional duration. Strongly recommended because quality and bitrate cannot be estimated without it.

width, heightinteger

Optional source dimensions. Required only when estimating resolution changes.

platformstring

Optional platform key from /api/v1/platforms. Applies that platform's safe target.

targetMbnumber

Optional custom file-size ceiling. Overrides the selected platform target.

settingsobject

Optional compressor settings: mode, preset, targetSizeMb, crf, resolution, maxResolution, bitrateKbps, codec, and outputFormat.

Response fields

verdictstring

fits_as_is, compress_recommended, or no_target. Safe to use in application logic.

estimateobject | null

Predicted output for the requested settings. Null when the inputs cannot determine an honest estimate.

recommendationobject | null

Settings expected to fit the target, including estimated video bitrate and quality guidance.

notes[]string[]

Plain-language caveats that are useful to show to an end user.

compressUrlstring

The matching VidSmaller web tool for a person who wants to finish the job manually.

Example response

{
  "ok": true,
  "input": { "sizeBytes": 158020403, "sizeMb": 150.7, "durationSeconds": 596 },
  "target": {
    "platform": "discord",
    "safeTargetMb": 19,
    "statedLimitMb": 20,
    "verifiedAt": "2026-09-14"
  },
  "verdict": "compress_recommended",
  "fitsAsIs": false,
  "estimate": {
    "settings": { "mode": "preset", "preset": "balanced", "codec": "libx264" },
    "outputMb": 90.4,
    "savedPercent": 40,
    "fitsTarget": false,
    "jobSeconds": 123
  },
  "recommendation": {
    "settings": { "mode": "target_size", "targetSizeMb": 19 },
    "outputMb": 19,
    "quality": { "videoKbps": 134, "verdict": "rough" }
  }
}

/api/v1/video/jobs

Creates an asynchronous compression job that aims at target_size_mb. Use either a public source URL or an uploaded-file token.

POSTBearer API key required

Option A: public video URL

Use source_url for a publicly reachable direct video file. VidSmaller checks the real source size before reserving credits.

curl -s https://vidsmaller.com/api/v1/video/jobs \
  -H "Authorization: Bearer $VIDSMALLER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_url": "https://cdn.example.com/input.mp4",
    "target_size_mb": 25,
    "codec": "h264",
    "max_resolution": "1080p",
    "webhook_url": "https://example.com/webhooks/vidsmaller"
  }'

Option B: local file upload

Request a signed upload URL, PUT the bytes directly to storage, then create the job with the returned upload_token.

# 1. Request a one-hour signed upload URL
curl -s https://vidsmaller.com/api/v1/video/uploads \
  -H "Authorization: Bearer $VIDSMALLER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename":"input.mp4","file_size":52428800,"content_type":"video/mp4"}'

# 2. PUT the file to upload.url with the returned Content-Type header
# 3. Create the job with the returned upload_token
curl -s https://vidsmaller.com/api/v1/video/jobs \
  -H "Authorization: Bearer $VIDSMALLER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"upload_token":"UPLOAD_TOKEN","target_size_mb":25}'

Request fields

source_urlHTTPS URL

Public direct video URL. Use this or upload_token, never both.

upload_tokenstring

Token returned after requesting a signed upload URL. Use this or source_url.

target_size_mbnumber

Required output ceiling in MiB.

codecstring

h264 by default, or h265 when the account's paid capability allows it.

max_resolutionstring

Optional ceiling: 2160p, 1440p, 1080p, 720p, 576p, 480p, or 360p.

output_formatstring

Optional output container: mp4 by default, mkv, webm, or mov.

webhook_urlHTTPS URL

Optional terminal-event callback. Private-network addresses and redirects are rejected.

Check status and download

Poll until job.status is completed or failed. A completed job returns an authenticated, short-lived download_url. Use the same bearer key for the status and download requests.

curl -H "Authorization: Bearer $VIDSMALLER_API_KEY" \
  https://vidsmaller.com/api/v1/video/jobs/JOB_ID

Signed webhooks

Receive a callback instead of polling when a job reaches a terminal state.

Events are video.job.completed, video.job.failed, and video.job.expired.

Verify x-vidsmaller-signature by computing HMAC-SHA256 over timestamp + "." + rawBody.

Use the webhook signing secret shown when the API key is created. The signature header starts with v1=.

Errors

Errors use JSON responses. The status code tells you whether to fix the request, sign in again, buy credits, or retry later.

400

Invalid or missing request field.

Read the error message and correct the payload.

401

Missing, invalid, or deleted API key.

Send a valid bearer key or create a new one.

402

Not enough credits for the job.

Add credits, then create the job again.

404

Job or download not found for this key.

Check the ID and use the key that created the job.

409

The upload or job is not in the required state.

Check the current status before retrying the action.

429

Request or concurrency limit reached.

Wait and retry with backoff.

500

VidSmaller could not complete the request.

Retry later. Contact support if the problem continues.

Limits & fair use

The API follows the same product limits as the web compressor.

Public read-only endpoints allow 600 requests per hour per IP.
Compression jobs use your account's credits, file-size limits, codec access, and burst limits.
API v1 may add response fields, but existing fields will not change meaning.
Commercial use is allowed. A link to VidSmaller is appreciated but not required.

If a platform limit is wrong or an API request behaves unexpectedly, email support@vidsmaller.com

API questions

Short answers to the integration decisions that are easy to miss in the endpoint reference.

Can the API compress a public URL or a local file?

Both. Send source_url for a publicly reachable direct video link, or request a one-hour signed upload URL, PUT a local file directly to storage, and create the job with its upload_token. A share page is not a direct video URL.

How do I know when an asynchronous job is finished?

Poll GET /api/v1/video/jobs/{id} until the status is completed or failed, or provide webhook_url when creating the job. Webhooks are signed with HMAC-SHA256 and fire for completed, failed, and expired terminal events.

Does the API support batch compression?

Submit one job per video; there is no multi-file job endpoint. You can create independent jobs from your own queue, subject to your account's burst and concurrency limits. A 429 response means to pause and retry with backoff.

Does the API have separate pricing or credits?

No. API jobs and the web compressor share the same VidSmaller credit balance, file-size limit, codec access, and burst limits. The exact credit reservation is made when a job is created, and failed processing is refunded automatically.

What should my integration do when a compression job fails?

Treat failed as a terminal state, record the returned error, and let the user retry with a valid source or different settings. Credits reserved for failed processing are returned automatically; repeated 429 or 500 responses should use delayed exponential backoff rather than an immediate retry loop.

Related resources

Video compression calculator Discord upload limits Terms of Service

Return to home

Video Compression API — Exact-Size Output

Start in 3 steps

Create a key

Create a job

Get the result

Free read-only endpoints

One compression workflow

Two input options

Stable v1 contract

Authentication & credits

/api/v1/platforms

Response fields

/api/v1/estimate

Request fields

Response fields

Example response

/api/v1/video/jobs

Option A: public video URL

Option B: local file upload

Request fields

Check status and download

Signed webhooks

Errors

Limits & fair use

API questions

Related resources