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.

How It Works

1

Get Presigned Upload URL

Request a secure presigned URL to upload your video directly to cloud storage.

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 the upload completion with our API to verify the file was successfully stored.

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.

System Endpoints

GET/health-check

Check the health status of the API Gateway service. Used for monitoring and load balancer health 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

API Endpoints

POST/v1/upload/presigned-url

Request a presigned URL for direct upload to cloud storage.

Request Body

{
  "filename": "video.mp4",
  "contentType": "video/mp4",
  "fileSize": 12345678
}

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
  }'
PUTDirect Upload to Storage

Use the presigned URL to upload your file directly. No API key required for this step.

cURL Example

# Replace UPLOAD_URL with the uploadUrl from step 1
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: video/mp4" \
  --data-binary @/path/to/video.mp4
POST/v1/upload/confirm

Confirm that the upload completed successfully.

Request Body

{
  "filename": "1234567890-video.mp4",
  "fileSize": 12345678
}

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

Create a new transcode job using the uploaded file. Supports both simple presets and advanced FFmpeg options.

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

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

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"

Additional Endpoints

GET/v1/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 - Filter jobs created after this timestamp
  • • until - Filter 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 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"

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

Quick Start

1. Get presigned upload URL

2. Upload video file

3. Confirm upload

4. Create transcode job

5. Monitor job status

6. Download processed video

Rate Limits

• API requests: 1000/hour

• File size: Up to 2GB

• Concurrent jobs: 5 per user

Need Help?

• Check the dashboard

• View your jobs

• Email: support@ffmpeg-micro.com