Developer Guide

FFmpeg Micro API Documentation

Transform videos with our simple, secure API. Upload, transcode, and download processed videos.

🚀 Access Your API

All API requests should be sent to:
https://api.ffmpeg-micro.com

Include your API key in the Authorization header:
Authorization: Bearer YOUR_API_KEY

💡 Get your API key from the API Keys page in your dashboard.

New to the API?

Follow our quickstart guide to make your first request. You'll go from upload to finished output in minutes with working code examples for curl, Node.js, and Python.

Start the Quickstart →
Workflow Overview
Five quick steps from upload to download.
1
Get Presigned Upload URL

Request a presigned URL with filename, content type, and file size in bytes. Send fileSize as a JSON number (not a quoted string or human-readable size).

2
Upload Your Video

Use the presigned URL to upload your video file directly to storage (no API key needed for upload).

3
Confirm Upload

Confirm with the same filename and byte size as JSON numbers; the API checks the object in storage matches what you declared.

4
Create Transcode Job

Submit a transcode job with your desired output format and quality. Get job ID immediately.

5
Monitor & Download

Poll for job status, and when complete, download your processed video.

API Endpoints

Core routes for uploads, transcodes, and downloads.

Want to explore these endpoints interactively?

The API Playground lets you browse each endpoint, see the request shape and headers, and copy ready-to-run cURL commands without leaving the docs.

Open API Playground →
post
/v1/upload/presigned-url
Step 1 · Presigned Upload URL
Request a presigned URL so the client can upload media straight to Cloud Storage.
Request Body
{
  "filename": "video.mp4",
  "contentType": "video/mp4",
  "fileSize": 12345678
}

fileSize must be a JSON number (size in bytes), not a string. Quoted values like "1024" or human-readable sizes are rejected with 400.

Response
{
  "success": true,
  "result": {
    "uploadUrl": "https://storage.googleapis.com/...",
    "filename": "1234567890-video.mp4"
  }
}
cURL Example
curl -X POST https://api.ffmpeg-micro.com/v1/upload/presigned-url \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "filename": "video.mp4",
    "contentType": "video/mp4",
    "fileSize": 12345678
  }'
put
uploadUrl (from step 1)
Step 2 · Upload Media
Use the presigned URL to upload your file directly. No API key required for this step.
cURL Example
# Replace UPLOAD_URL with the exact uploadUrl value from step 1
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: video/mp4" \
  --data-binary @/path/to/video.mp4
post
/v1/upload/confirm
Step 3 · Confirm Upload
Confirm the upload completion with our API to verify the file was successfully stored.
Request Body
{
  "filename": "1234567890-video.mp4",
  "fileSize": 12345678
}

fileSize must be a JSON number (bytes), same as step 1—not a string. It must match the uploaded object in storage; wrong types return 400 with an explicit validation error.

cURL Example
curl -X POST https://api.ffmpeg-micro.com/v1/upload/confirm \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "filename": "1234567890-video.mp4",
    "fileSize": 12345678
  }'
post
/v1/transcodes
Step 4 · Create Transcode Job
Create a new transcode job using the uploaded file. Supports both simple presets and advanced FFmpeg options.
Note: Replace <YOUR_BUCKET> below with the bucket name from Step 3's fileUrl response.
Request Body (Simple Mode)
{
  "inputs": [
    { "url": "gs://<YOUR_BUCKET>/1234567890-video.mp4" }
  ],
  "outputFormat": "mp4",
  "preset": {
    "quality": "medium",
    "resolution": "1080p"
  }
}
Request Body (Advanced Mode)

Note: -filter_complex is not supported. See supported alternatives.

{
  "inputs": [
    { "url": "gs://<YOUR_BUCKET>/1234567890-video.mp4" }
  ],
  "outputFormat": "mp4",
  "options": [
    { "option": "-c:v", "argument": "libx264" },
    { "option": "-crf", "argument": "23" },
    { "option": "@text-overlay", "argument": {
      "text": "Hello World",
      "style": { "fontSize": 60, "x": "0.15*w", "y": "(h-text_h)/2" }
    }}
  ]
}
Response
{
  "id": "job-uuid",
  "status": "pending",
  "inputs": [
    { "url": "gs://<YOUR_BUCKET>/1234567890-video.mp4" }
  ],
  "output_format": "mp4",
  "created_at": "2025-01-01T00:00:00Z"
}
cURL Example
curl -X POST https://api.ffmpeg-micro.com/v1/transcodes \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "inputs": [
      { "url": "gs://<YOUR_BUCKET>/1234567890-video.mp4" }
    ],
    "outputFormat": "mp4",
    "preset": {
      "quality": "medium",
      "resolution": "1080p"
    }
  }'
get
/v1/transcodes/:id
Step 5 · Check Job Status
Check the status of a transcode job.
Response
{
  "success": true,
  "jobId": "job-uuid",
  "status": "completed",
  "outputUrl": "gs://output-bucket/processed-video.mp4",
  "createdAt": "2025-01-01T00:00:00Z",
  "completedAt": "2025-01-01T00:02:30Z"
}
cURL Example
curl -X GET https://api.ffmpeg-micro.com/v1/transcodes/job-uuid \
  -H "Authorization: Bearer YOUR_API_KEY"
get
/v1/transcodes/:id/download
Step 6 · Download Processed Video
Get a signed download URL for the processed video.
Response
{
  "url": "https://storage.googleapis.com/...?X-Goog-Signature=..."
}
cURL Example
# Get signed URL
curl -X GET https://api.ffmpeg-micro.com/v1/transcodes/job-uuid/download \
  -H "Authorization: Bearer YOUR_API_KEY"

# Then download the file
curl -O "$DOWNLOAD_URL"
post
/v1/transcribe
Transcribe Audio → SRT
Generate subtitles from an audio or video file. Uses Whisper under the hood to produce an SRT file stored in your output bucket. Returns a queued-job envelope identical in shape to /v1/transcodes.
Request Body
{
  "media_url": "gs://<YOUR_BUCKET>/1234567890-audio.mp3",
  "language": "en",              // optional — auto-detected by default
  "task": "transcribe"           // optional — "transcribe" or "translate"
}
Response
{
  "id": "job-uuid",
  "status": "pending",
  "media_url": "gs://<YOUR_BUCKET>/1234567890-audio.mp3",
  "output_format": "srt",
  "created_at": "2026-04-19T17:22:44.396Z"
}
cURL Example
curl -X POST https://api.ffmpeg-micro.com/v1/transcribe \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{ "media_url": "gs://<YOUR_BUCKET>/1234567890-audio.mp3" }'
get
/v1/transcribe/:id
Check Transcribe Status
Poll until status is completed or failed. Same polling shape as /v1/transcodes/:id.
cURL Example
curl -X GET https://api.ffmpeg-micro.com/v1/transcribe/job-uuid \
  -H "Authorization: Bearer YOUR_API_KEY"
get
/v1/transcribe/:id/download
Download SRT
Returns a signed HTTPS URL for the generated SRT (10-minute TTL). You can drop this URL straight into a transcode's subtitles='…' filter to burn captions into a video.
Response
{
  "url": "https://storage.googleapis.com/...?X-Goog-Signature=..."
}
cURL Example
curl -X GET https://api.ffmpeg-micro.com/v1/transcribe/job-uuid/download \
  -H "Authorization: Bearer YOUR_API_KEY"
get
/v1/transcodes
List Transcodes
List all transcode jobs with filtering and pagination.
Query Parameters
  • • status — Filter by status (queued, processing, completed, failed)
  • • page — Page number (default: 1)
  • • limit — Items per page (default: 20, max: 100)
  • • since — Jobs created after this timestamp
  • • until — Jobs created before this timestamp
cURL Example
curl -X GET "https://api.ffmpeg-micro.com/v1/transcodes?status=completed&page=1&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"
get
/v1/transcodes/:id
Get Transcode Details
Get detailed information about a specific transcode job.
cURL Example
curl -X GET "https://api.ffmpeg-micro.com/v1/transcodes/job-uuid" \
  -H "Authorization: Bearer YOUR_API_KEY"
get
/health-check
Health Check
Monitor gateway health for load balancers or uptime checks.
Response
{
  "ok": true,
  "timestamp": "2025-10-23T14:30:45.123Z",
  "uptime": 3600.5,
  "supabase": {
    "ok": true,
    "status": 200,
    "statusText": "OK",
    "connected": true
  }
}
cURL Example
curl -X GET https://api.ffmpeg-micro.com/health-check

Supported Formats

Input Formats
  • • MP4 (H.264, H.265)
  • • WebM (VP8, VP9)
  • • AVI (various codecs)
  • • MOV (QuickTime)
  • • MKV (Matroska)
  • • FLV (Flash Video)
Output Formats
  • • MP4 (H.264 + AAC)
  • • WebM (VP9 + Opus)
  • • Quality: low, medium, high
  • • Resolutions: 480p, 720p, 1080p, 4K
Video Effects
Apply high-level transformations without hand-writing FFmpeg filters.
  • • @text-overlay — add styled text overlays
  • • @quote-card — generate social-ready quote cards
View all effects →
Inspect Files with FFprobe
Extract metadata before processing.

Check duration, codecs, resolution, and stream properties before you run a transcode job.

Learn about FFprobe →
MCP Server
Control FFmpeg Micro from your AI assistant.

Connect Claude Code, Cursor, or any MCP-compatible tool and transcode videos with natural language.

Set up MCP →
Need Help?
• Browse support articles
• Check the dashboard
• View your jobs
• Email: javid@ffmpeg-micro.com
Read & Reference
AI-friendly markdown alternates are available for documentation and every published blog post.
• Blog (HTML)
• /docs.md — this page in markdown for AI consumption
• /blog/<slug>.md — markdown alternate for any published post