Quickstart
Get started with the FetchMedia Commands API in under 5 minutes by making your first API call to run an FFmpeg command on a video.
Overview
The FetchMedia Commands API allows you to programmatically execute FFmpeg commands on media files from public URLs. This enables a wide range of media processing tasks directly through the API.
This API is optimized for:
-
Running FFmpeg commands without managing infrastructure
-
Asynchronous processing with webhook notifications
-
Handling complex, multi-step FFmpeg workflows
-
Securely storing and retrieving processed media files
All requests require API key authentication via the X-API-KEY header.
Prerequisites
Before starting, ensure you have:
-
A FetchMedia account (free tier available)
-
An HTTP client like cURL, Postman, or a programming language with HTTP support
-
A publicly accessible URL to a media file (e.g., a video, audio, or image file).
Create Account
Visit https://app.fetchmedia.io and sign up with your email.
Verify Email
Check your inbox and click the verification link.
Generate API Key
Navigate to the API Keys section in your dashboard. Click "Create New Key" and copy the generated key (format: fm_1234567890abcdef).
Run a Command
Use this example to run a simple FFmpeg command that converts a video to MP4.
const response = await fetch('https://api.fetchmedia.io/v1/commands', {
method: 'POST',
headers: {
'X-API-KEY': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"ffmpeg_command": "ffmpeg -i {{in_1}} -c:v libx264 -c:a aac {{out_1}}",
"input_files": {
"in_1": "https://www.w3schools.com/html/mov_bbb.mp4"
},
"output_files": {
"out_1": "output.mp4"
}
})
});
const data = await response.json();
console.log(data.command_id);
curl -X POST https://api.fetchmedia.io/v1/commands \
-H "X-API-KEY: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"ffmpeg_command": "ffmpeg -i {{in_1}} -c:v libx264 -c:a aac {{out_1}}",
"input_files": {
"in_1": "https://www.w3schools.com/html/mov_bbb.mp4"
},
"output_files": {
"out_1": "output.mp4"
}
}'
import requests
response = requests.post(
'https://api.fetchmedia.io/v1/commands',
headers={
'X-API-KEY': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
json={
"ffmpeg_command": "ffmpeg -i {{in_1}} -c:v libx264 -c:a aac {{out_1}}",
"input_files": {
"in_1": "https://www.w3schools.com/html/mov_bbb.mp4"
},
"output_files": {
"out_1": "output.mp4"
}
}
)
print(response.json()['command_id'])
Poll for Results
The initial response provides a command_id. Poll the GET /v1/commands/{id} endpoint until the status is success.
// Poll example
const pollStatus = async (id) => {
const statusResponse = await fetch(`https://api.fetchmedia.io/v1/commands/${id}`, {
headers: { 'X-API-KEY': 'YOUR_API_KEY' }
});
const data = await statusResponse.json();
if (data.status === 'success') {
// Assuming 'out_1' is the key for your output file
console.log('Download:', data.output_files.out_1.download_url);
return data.output_files.out_1.download_url;
} else if (data.status === 'running' || data.status === 'pending') {
// Wait and poll again
setTimeout(() => pollStatus(id), 5000);
} else {
console.error('Command failed:', data.processing_errors);
}
};
def poll_status(command_id):
url = f"https://api.fetchmedia.io/v1/commands/{command_id}"
headers = {'X-API-KEY': 'YOUR_API_KEY'}
while True:
response = requests.get(url, headers=headers)
data = response.json()
status = data.get('status')
if status == 'success':
# Assuming 'out_1' is the key for your output file
download_url = data['output_files']['out_1']['download_url']
print(f"Download: {download_url}")
return download_url
elif status in ['running', 'pending']:
# Wait 5 seconds and poll again
time.sleep(5)
else:
print(f"Command failed: {data.get('processing_errors')}")
return None
Download Processed Video
Once the command is successful, the output_files object in the response will contain the download_url for each output. Use this URL to download your processed file. The URL will redirect to a temporary, secure download link.
Congratulations! You've processed your first video with the Commands API. Check your dashboard at https://app.fetchmedia.io for usage stats.
Last updated Jan 23, 2026
Built with Documentation.AI