Making API Requests

The FFmpeg API accepts requests to process media files using FFmpeg commands. All requests are made to the main endpoint with file uploads and command parameters.

Endpoint

POST https://api.ffmpeg-api.com/ffmpeg/run

Request Format

The API uses multipart/form-data for file uploads and accepts the following parameters:

Required Parameters

Parameter	Type	Description
`command`	JSON string	FFmpeg command structure with inputs and outputs
File uploads	File	Media files referenced in the command

Headers

Key	Value	Required
`Authorization`	`Basic <Your Auth Key>`	Yes
`Content-Type`	`multipart/form-data`	Automatically set by curl

Command Structure

The command parameter must be a JSON string with the following structure:

{
  "inputs": [
    {
      "options": [],
      "file": "input_filename"
    }
  ],
  "outputs": [
    {
      "options": [],
      "file": "output_filename"
    }
  ]
}

Input Object

options: Array of FFmpeg input options (e.g., ["-t", "10"] for duration)
file: Filename that matches the uploaded file parameter

Output Object

options: Array of FFmpeg output options (e.g., ["-c:v", "libx264"] for video codec)
file: Desired output filename

Example Requests

Basic GIF to MP4 Conversion

Request Data:

File: input.gif (your GIF file)
Command: {"inputs":[{"options":[],"file":"input.gif"}],"outputs":[{"options":[],"file":"output.mp4"}]}

cURL Example:

curl -F "input.gif=@/path/to/your/file.gif" \
  https://api.ffmpeg-api.com/ffmpeg/run \
  -H 'Authorization: Basic YOUR_AUTH_KEY_HERE' \
  -F 'command={"inputs":[{"options":[],"file":"input.gif"}],"outputs":[{"options":[],"file":"output.mp4"}]}'

Video with Custom Options

Request Data:

File: video.mp4 (your video file)
Command: {"inputs":[{"options":["-ss","00:00:10","-t","30"],"file":"video.mp4"}],"outputs":[{"options":["-c:v","libx264","-crf","23"],"file":"output.mp4"}]}

cURL Example:

curl -F "video.mp4=@/path/to/video.mp4" \
  https://api.ffmpeg-api.com/ffmpeg/run \
  -H 'Authorization: Basic YOUR_AUTH_KEY_HERE' \
  -F 'command={"inputs":[{"options":["-ss","00:00:10","-t","30"],"file":"video.mp4"}],"outputs":[{"options":["-c:v","libx264","-crf","23"],"file":"output.mp4"}]}'

Multiple Input Files

Request Data:

Files: video.mp4, audio.mp3
Command: {"inputs":[{"options":[],"file":"video.mp4"},{"options":[],"file":"audio.mp3"}],"outputs":[{"options":["-c:v","copy","-c:a","aac"],"file":"output.mp4"}]}

cURL Example:

curl -F "video.mp4=@/path/to/video.mp4" \
  -F "audio.mp3=@/path/to/audio.mp3" \
  https://api.ffmpeg-api.com/ffmpeg/run \
  -H 'Authorization: Basic YOUR_AUTH_KEY_HERE' \
  -F 'command={"inputs":[{"options":[],"file":"video.mp4"},{"options":[],"file":"audio.mp3"}],"outputs":[{"options":["-c:v","copy","-c:a","aac"],"file":"output.mp4"}]}'

File Upload Guidelines

ℹ️

File parameter names in the request must exactly match the file field in your command’s inputs.

File Upload Requirements

Parameter names: Must match the file field in your command inputs
File paths: Any accessible file path (implementation depends on your tool/language)
Multiple files: Upload all files referenced in your command’s inputs

File Size Limits

Maximum file size: 100MB per file (will be increased in the future)

Response Format

Success Response

{
  "ok": true,
  "result": [
    {
      "file": "https://.../output.mp4?...",
      "size": 104897
    }
  ]
}

Response Fields:

ok: Boolean indicating request success
result: Array of output files
result[].file: Signed URL to download the processed file (valid for 1 hour)
result[].size: File size in bytes

Error Response

{
  "ok": false,
  "error": "Error message describing what went wrong"
}

Best Practices

⚠️

Always validate your FFmpeg command locally before sending it to the API to avoid unnecessary usage charges.

Error Prevention

Check file formats: Ensure input files are in supported formats
Validate paths: Use absolute paths for file uploads
Test commands: Validate FFmpeg syntax before API calls
Handle timeouts: Implement retry logic for large file processing

Language-Specific Examples

Python (requests)

import requests
import json
 
files = {
    'input.gif': open('/path/to/file.gif', 'rb'),
    'command': (None, json.dumps({
        "inputs": [{"options": [], "file": "input.gif"}],
        "outputs": [{"options": [], "file": "output.mp4"}]
    }))
}
 
headers = {
    'Authorization': 'Basic YOUR_AUTH_KEY_HERE'
}
 
response = requests.post(
    'https://api.ffmpeg-api.com/ffmpeg/run',
    files=files,
    headers=headers
)
 
result = response.json()
if result['ok']:
    output_url = result['result'][0]['file']
    print(f"Download your file: {output_url}")

JavaScript (Node.js)

const FormData = require('form-data');
const fs = require('fs');
const fetch = require('node-fetch');
 
const form = new FormData();
form.append('input.gif', fs.createReadStream('/path/to/file.gif'));
form.append('command', JSON.stringify({
    inputs: [{ options: [], file: 'input.gif' }],
    outputs: [{ options: [], file: 'output.mp4' }]
}));
 
const response = await fetch('https://api.ffmpeg-api.com/ffmpeg/run', {
    method: 'POST',
    headers: {
        'Authorization': 'Basic YOUR_AUTH_KEY_HERE',
        ...form.getHeaders()
    },
    body: form
});
 
const result = await response.json();
if (result.ok) {
    const outputUrl = result.result[0].file;
    console.log(`Download your file: ${outputUrl}`);
}

PHP

<?php
$ch = curl_init();
 
$postFields = [
    'input.gif' => new CURLFile('/path/to/file.gif'),
    'command' => json_encode([
        'inputs' => [['options' => [], 'file' => 'input.gif']],
        'outputs' => [['options' => [], 'file' => 'output.mp4']]
    ])
];
 
curl_setopt($ch, CURLOPT_URL, 'https://api.ffmpeg-api.com/ffmpeg/run');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postFields);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Basic YOUR_AUTH_KEY_HERE'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
 
$response = curl_exec($ch);
$result = json_decode($response, true);
 
if ($result['ok']) {
    $outputUrl = $result['result'][0]['file'];
    echo "Download your file: " . $outputUrl;
}
curl_close($ch);
?>

Other Tools

HTTPie:

http --form POST https://api.ffmpeg-api.com/ffmpeg/run \
    'Authorization:Basic YOUR_AUTH_KEY_HERE' \
    input.gif@/path/to/file.gif \
    command='{"inputs":[{"options":[],"file":"input.gif"}],"outputs":[{"options":[],"file":"output.mp4"}]}'

Postman:

Method: POST
URL: https://api.ffmpeg-api.com/ffmpeg/run
Headers: Authorization: Basic YOUR_AUTH_KEY_HERE
Body: form-data with file upload and command field

ℹ️

For more examples and use cases, check out our FFmpeg recipes section.

Authentication GB-Seconds