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.

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.

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)
{
  "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"
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 →
Need Help?
• Browse support articles
• Check the dashboard
• View your jobs
• Email: javid@ffmpeg-micro.com