API Reference

Complete reference for all FFmpeg API endpoints. Quick to scan, easy to implement.

📚 Complete OpenAPI Specification

Machine-readable API spec for code generation and testing

Download OpenAPI →

Base URL & Authentication

Base URL: https://api.ffmpeg-api.com

Authentication: All endpoints require Basic Auth header with your API key:

Authorization: Basic YOUR_API_KEY

🔑

Get your API header from the Dashboard. It comes pre-formatted as Basic abc123...

🎬 Processing Endpoints

POST /ffmpeg/process

Transform media files using FFmpeg commands.

POST /ffmpeg/processCore Endpoint

Request Body

{
"task": {
  "inputs": [
    {
      "file_path": "dir_abc123/input.mp4",
      "options": ["-ss", "10", "-t", "30"]
    }
  ],
  "outputs": [
    {
      "file": "output.mp4",
      "options": ["-crf", "23", "-preset", "medium"],
      "maps": ["0:v", "0:a"]
    }
  ],
  "filter_complex": "[0:v]scale=1280:720[out]"
}
}

Required Fields

• task.inputs[] - Input files array
• task.outputs[] - Output specifications
• inputs[].file_path - File path from upload
• outputs[].file - Output filename

Optional Fields

• inputs[].options[] - Input FFmpeg options
• outputs[].options[] - Output FFmpeg options
• outputs[].maps[] - Stream mappings
• filter_complex - Filter graph string

Response

{
"ok": true,
"result": [
  {
    "file_name": "output.mp4",
    "size_bytes": 1234567,
    "download_url": "https://storage.example.com/result.mp4"
  }
],
"usage": {
  "time_sec": 12.5,
  "input_size_gb": 0.098,
  "output_size_gb": 0.015,
  "gb_sec": 1.4125
}
}

Important: All input files must be in the same directory. Output filenames cannot conflict with existing input files.

POST /ffmpeg/run [Deprecated]

Legacy endpoint for multipart uploads. Use /ffmpeg/process instead.

⚠️

Migration Required

This endpoint is deprecated. See the Migration Guide for updating your code.

🔍 Analysis Endpoints

POST /ffprobe/analyze

Analyze media metadata using FFprobe. Extract technical information about uploaded files including format details, stream properties, and frame/packet data.

POST /ffprobe/analyzeAnalysis

Request Body

{
"file_path": "dir_abc123/video.mp4",
"probe": {
  "format": ["duration", "size", "bit_rate"],
  "streams": ["codec_name", "width", "height", "sample_rate"],
  "select_streams": "v:0"
}
}

Required Fields

• file_path - File path from upload (format: dir_id/file_name)

Optional Fields

• probe.format[] - Format fields to return
• probe.streams[] - Stream fields to return
• probe.select_streams - Stream selection (e.g., “v:0”)
• probe.frames[] - Frame data (requires select_streams)

Probe Options

Section Arrays

• format[] - File format info (duration, size, bit_rate)
• streams[] - Stream properties (codec, dimensions, sample_rate)
• chapters[] - Chapter information
• programs[] - Program data (MPEG-TS)
• frames[] - Frame-level data
• packets[] - Packet-level data

Control Options

• select_streams - Stream selector (“v:0”, “a”, “s:1”)
• read_intervals - Time/frame ranges (“0%+10”, “#500”)
• count_frames - Count frames without dumping
• analyzeduration - Analysis time limit (”10s”)
• probesize - Probe size limit (“10M”)

Response

{
"ok": true,
"result": {
  "format": {
    "duration": "120.5",
    "size": "15728640",
    "bit_rate": "1048576"
  },
  "streams": [
    {
      "codec_name": "h264",
      "width": 1920,
      "height": 1080,
      "sample_rate": "48000"
    }
  ]
},
"usage": {
  "time_sec": 2.1,
  "input_size_gb": 0.015,
  "output_size_gb": 0.0001,
  "gb_sec": 0.0315
}
}

Tip: Empty arrays [] return all fields for that section. Use specific field names to reduce response size.

Important: frames and packets require select_streams to prevent excessive output. Resource limits: 60s max analysis, 50MB max probe size.

📁 File Management Endpoints

POST /file

Request Body

{
"file_name": "video.mp4",
"dir_id": "dir_abc123"  // optional
}

Parameters

file_name *required - Filename for the uploaded file

dir_id optional - Directory ID (creates temp directory if omitted)

Response

{
"ok": true,
"file": {
  "dir_id": "dir_abc123",
  "file_name": "video.mp4",
  "file_path": "dir_abc123/video.mp4",
  "added_on": "2024-01-01T00:00:00Z"
},
"upload": {
  "url": "https://presigned-upload-url...",
  "method": "PUT",
  "headers": {},
  "expiresInSeconds": 300
}
}

GET /file/{dirId}/{fileName}

Get file metadata (type and size) for a stored file.

GET /file/{dirId}/{fileName}

URL Parameters

dirId - Directory ID (1-64 chars, A-Z a-z 0-9 _ -)

fileName - File name (1-255 chars, no slashes)

Response

{
"ok": true,
"file_info": {
  "file_path": "dir_abc123/video.mp4",
  "file_type": "video/mp4",
  "file_size": 1048576
}
}

Note: This endpoint requires authentication and returns 404 if the file doesn’t exist or you don’t have access.

POST /directory

Create a temporary working directory (optional for organization).

POST /directory

Request Body

{
"ttl": 86400  // optional, seconds (default: 24 hours)
}

Response

{
"ok": true,
"directory": {
  "id": "dir_abc123",
  "ttl": 86400
}
}

GET /directory

List all your directories.

GET /directory

Response

{
"ok": true,
"directories": [
  {
    "id": "dir_abc123",
    "ttl": 86400,
    "added_on": "2024-01-01T10:00:00Z"
  }
]
}

GET /directory/{dirId}

List files in a specific directory.

GET /directory/{dirId}

URL Parameters

dirId *required - Directory ID to list files from

Response

{
"ok": true,
"files": [
  {
    "file_name": "video.mp4",
    "added_on": "2024-01-01T10:30:00Z"
  },
  {
    "file_name": "audio.wav",
    "added_on": "2024-01-01T10:35:00Z"
  }
]
}

⚠️ Error Responses

All error responses follow the same format:

{
  "ok": false,
  "error": "Descriptive error message"
}

HTTP Status Codes

Client Errors (4xx)

400 Bad Request - Invalid JSON, missing fields
401 Unauthorized - Invalid API key
403 Forbidden - Quota exceeded, expired URL
404 Not Found - File/directory doesn’t exist

Server Errors (5xx)

500 Internal Error - FFmpeg processing failed
502 Bad Gateway - Upstream service issue
503 Service Unavailable - Temporary outage

Common Error Scenarios

400 “Invalid task format”

Common causes:

Missing required fields (inputs, outputs)
Invalid file_path format
Output filename conflicts with input
Mixed directories in inputs

401 “Invalid API key”

Check your authentication:

API key format: Basic abc123…
Header name: Authorization (not Auth)
Copy key exactly from dashboard

403 “Upload URL expired”

Upload URLs expire after 5 minutes:

Request new upload URL from /file
Upload immediately after getting URL
Implement retry logic for expired URLs

500 “FFmpeg processing failed”

Processing issues:

Invalid FFmpeg options syntax
Incompatible input/output formats
Complex filter graph errors
File corruption or unsupported codec

Quick Examples

Upload and Process

# 1. Register file
curl -X POST https://api.ffmpeg-api.com/file \\
  -H "Authorization: Basic YOUR_API_KEY" \\
  -d '{"file_name":"video.mp4"}'
 
# 2. Upload to presigned URL
curl -X PUT "$UPLOAD_URL" --data-binary @video.mp4
 
# 3. Process
curl -X POST https://api.ffmpeg-api.com/ffmpeg/process \\
  -H "Authorization: Basic YOUR_API_KEY" \\
  -d '{"task":{"inputs":[{"file_path":"dir_123/video.mp4"}],"outputs":[{"file":"compressed.mp4","options":["-crf","28"]}]}}'

Analyze Media

# Analyze video properties
curl -X POST https://api.ffmpeg-api.com/ffprobe/analyze \\
  -H "Authorization: Basic YOUR_API_KEY" \\
  -d '{
    "file_path": "dir_123/video.mp4",
    "probe": {
      "format": ["duration", "size"],
      "streams": ["codec_name", "width", "height"],
      "select_streams": "v:0"
    }
  }'

List Resources

# List directories
curl -H "Authorization: Basic YOUR_API_KEY" \\
  https://api.ffmpeg-api.com/directory
 
# List files in directory
curl -H "Authorization: Basic YOUR_API_KEY" \\
  https://api.ffmpeg-api.com/directory/dir_123

Need more details? See our guides:

Quick Start - Complete workflow walkthrough
Processing - Advanced FFmpeg operations
Examples - Production-ready code samples

FFprobe Advanced Usage