How to Process Video with a JSON API (FFmpeg Micro Request Examples)

You want to process video in your app, but you don't want to install FFmpeg, wrangle dependencies, or manage a transcoding server. You just want to send some JSON and get a result back. That's exactly what FFmpeg Micro does.

This post walks through real JSON request payloads for the most common video operations: compressing, converting formats, adding text overlays, and using custom FFmpeg options. Every example uses the actual FFmpeg Micro API, and every request is a single HTTP call.

How the FFmpeg Micro JSON API Works

FFmpeg Micro is a cloud API that lets you add video processing to any app with a single HTTP call. No FFmpeg installation, no server management.

The core endpoint is POST /v1/transcodes. You send a JSON body with your input video URL, the output format you want, and optionally a preset or custom FFmpeg options. The API returns a job ID, and you poll for the result.

Every request needs an Authorization: Bearer <YOUR_API_KEY> header. You get an API key when you sign up for a free account at ffmpeg-micro.com.

Compress a Video (Simple Preset Mode)

Most developers start here. You have a large MP4 and you need a smaller one. With the preset mode, you don't need to know any FFmpeg flags.

{
  "inputs": [{"url": "https://example.com/raw-video.mp4"}],
  "outputFormat": "mp4",
  "preset": {
    "quality": "medium",
    "resolution": "720p"
  }
}

Send that to POST /v1/transcodes and you get back a job object with an id. The quality field maps to FFmpeg's CRF values: low (CRF 28, smallest file), medium (CRF 23, balanced), and high (CRF 18, best quality). Resolution options are 480p, 720p, and 1080p.

The response looks like this:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "processing",
  "outputFormat": "mp4"
}

Poll GET /v1/transcodes/{id} until status is completed, then hit GET /v1/transcodes/{id}/download to get a signed download URL.

Convert Video Format (MP4 to WebM)

Format conversion is one line different. Change outputFormat and the API handles codec selection automatically.

{
  "inputs": [{"url": "https://example.com/video.mp4"}],
  "outputFormat": "webm"
}

FFmpeg Micro supports MP4, WebM, AVI, MOV, MKV, and FLV for video. For audio, you can output to MP3, M4A, AAC, WAV, OGG, Opus, and FLAC. Image extraction supports JPEG, PNG, GIF, and WebP.

No preset means the API uses sensible defaults for the target format.

Advanced Mode: Custom FFmpeg Options

Presets cover the common cases, but sometimes you need full control. The options array lets you pass raw FFmpeg flags as key-value pairs.

To compress with a specific codec and bitrate:

{
  "inputs": [{"url": "https://example.com/video.mp4"}],
  "outputFormat": "mp4",
  "options": [
    {"option": "-c:v", "argument": "libx264"},
    {"option": "-crf", "argument": "20"},
    {"option": "-c:a", "argument": "aac"},
    {"option": "-b:a", "argument": "128k"}
  ]
}

This gives you the same flexibility as a raw FFmpeg command line, but without the server. The API validates your options before processing, so you get clear error messages if something is wrong.

Add a Text Overlay with Virtual Options

FFmpeg Micro has "virtual options" for operations that would normally require complex filter chains. The @text-overlay virtual option adds text to your video with a single request.

{
  "inputs": [{"url": "https://example.com/video.mp4"}],
  "outputFormat": "mp4",
  "options": [
    {"option": "@text-overlay", "argument": "{\"text\": \"Subscribe!\", \"position\": \"bottom-center\", \"fontSize\": 48, \"fontColor\": \"white\"}"}
  ]
}

No filter graph syntax. No escaped colons. Just a JSON string describing what you want. The API translates it to the correct FFmpeg drawtext filter internally.

Upload Your Own Files First

The examples above use public HTTP URLs for the input video. If you need to process a file from your local system or a private source, use the three-step upload flow:

Step 1: Request a presigned upload URL.

curl -X POST https://www.ffmpeg-micro.com/v1/upload/presigned-url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "my-video.mp4", "contentType": "video/mp4", "fileSize": 10485760}'

Step 2: PUT your file to the returned uploadUrl (direct to cloud storage).

Step 3: Confirm the upload to get a fileUrl you can use in your transcode request.

curl -X POST https://www.ffmpeg-micro.com/v1/upload/confirm \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "my-video.mp4", "fileSize": 10485760}'

The fileUrl from Step 3 is a gs:// URL you pass as the url in your inputs array.

Putting It All Together with cURL

A complete cURL example that compresses a video to 720p:

curl -X POST https://www.ffmpeg-micro.com/v1/transcodes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [{"url": "https://example.com/video.mp4"}],
    "outputFormat": "mp4",
    "preset": {"quality": "medium", "resolution": "720p"}
  }'

One HTTP call, and your video is being processed in the cloud. No FFmpeg binary, no Docker container, no scaling headaches.

CLI vs. JSON API: A Quick Comparison

If you're used to FFmpeg on the command line, the mental model shift looks like this:

The JSON is more verbose, but it's also portable. Any language or platform that can make HTTP requests can process video. That includes no-code tools like Make.com and n8n, not just backend services.

Frequently Asked Questions

Can I process video from any URL or only uploaded files?

Both. You can pass any public HTTP/HTTPS URL as the input, or upload files through the presigned URL flow to get a private gs:// URL. Most developers start with public URLs for testing and switch to uploads for production.

What happens if I send invalid FFmpeg options?

The API validates your options before starting the job. You get a 400 error with a clear description of what went wrong, instead of a cryptic FFmpeg stderr dump.

How do I check if my video is done processing?

Poll GET /v1/transcodes/{id}. The status field will be processing, completed, or failed. For completed jobs, GET /v1/transcodes/{id}/download returns a signed URL to grab the output file.

Is there a free tier?

Yes. Sign up at ffmpeg-micro.com and you get free processing minutes to test the API. Paid plans start at $19/month for production workloads.

What formats does the API support?

Video: MP4, WebM, AVI, MOV, MKV, FLV. Audio: MP3, M4A, AAC, WAV, OGG, Opus, FLAC. Images: JPEG, PNG, GIF, WebP. You can also extract audio from video or generate thumbnails.