Get Started in 5 Minutes

Transform your first media file with FFmpeg API. Choose your path:

Easiest: AI Processing (Beta)

Describe what you want in plain English. No FFmpeg knowledge needed.

Full Control: FFmpeg Commands

Specify exact FFmpeg options for precise control over processing.

Before you start

Get your API key from the Dashboard.

Easiest: AI Processing

Just describe what you want in plain English. The AI figures out the right FFmpeg command and runs it for you. AI endpoints cost nothing extra — you only pay for the compute used.

🧪

AI Processing is in beta. Results depend on AI interpretation and may not always be perfect. Review the generated_command in responses.

Process from a URL

If your file is already hosted somewhere, this is the absolute simplest way to get started — one request, plain English:

curl -X POST https://api.ffmpeg-api.com/ai/ffmpeg/process \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [{ "file_path": "https://download.blender.org/peach/bigbuckbunny_movies/BigBuckBunny_320x180.mp4" }],
    "instructions": "Compress this video to 720p MP4 with good quality"
  }'

const response = await fetch('https://api.ffmpeg-api.com/ai/ffmpeg/process', {
  method: 'POST',
  headers: {
    'Authorization': 'Basic YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    inputs: [{ file_path: 'https://download.blender.org/peach/bigbuckbunny_movies/BigBuckBunny_320x180.mp4' }],
    instructions: 'Compress this video to 720p MP4 with good quality'
  })
})
 
const data = await response.json()
console.log(data.result[0].download_url)     // Download your processed file
console.log(data.generated_command)           // See what FFmpeg command the AI used

import requests
 
response = requests.post('https://api.ffmpeg-api.com/ai/ffmpeg/process',
    headers={
        'Authorization': 'Basic YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'inputs': [{'file_path': 'https://download.blender.org/peach/bigbuckbunny_movies/BigBuckBunny_320x180.mp4'}],
        'instructions': 'Compress this video to 720p MP4 with good quality'
    }
)
 
data = response.json()
print(data['result'][0]['download_url'])    # Download your processed file
print(data['generated_command'])            # See what FFmpeg command the AI used

That’s it. The URL is imported, the AI generates and runs the right FFmpeg command, and you get a download_url for the result.

Process an uploaded file

For local files, upload first, then process with AI:

# 1. Register and upload your file
UPLOAD_RESPONSE=$(curl -sS -X POST https://api.ffmpeg-api.com/file \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"file_name": "video.mov"}')
 
FILE_PATH=$(echo $UPLOAD_RESPONSE | jq -r '.file.file_path')
UPLOAD_URL=$(echo $UPLOAD_RESPONSE | jq -r '.upload.url')
 
curl -X PUT "$UPLOAD_URL" --data-binary @./video.mov
 
# 2. Process with plain English
curl -X POST https://api.ffmpeg-api.com/ai/ffmpeg/process \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"inputs\": [{\"file_path\": \"$FILE_PATH\"}],
    \"instructions\": \"Convert to MP4, resize to 720p, good compression\"
  }"

import fs from 'fs'
 
const API_KEY = 'Basic YOUR_API_KEY'
 
// 1. Register and upload your file
const fileRes = await fetch('https://api.ffmpeg-api.com/file', {
  method: 'POST',
  headers: { 'Authorization': API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({ file_name: 'video.mov' })
})
const { file, upload } = await fileRes.json()
 
await fetch(upload.url, { method: 'PUT', body: fs.readFileSync('./video.mov') })
console.log('Uploaded!')
 
// 2. Process with plain English
const processRes = await fetch('https://api.ffmpeg-api.com/ai/ffmpeg/process', {
  method: 'POST',
  headers: { 'Authorization': API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    inputs: [{ file_path: file.file_path }],
    instructions: 'Convert to MP4, resize to 720p, good compression'
  })
})
 
const result = await processRes.json()
console.log(result.result[0].download_url)   // Your processed file
console.log(result.generated_command)         // The FFmpeg command the AI created

import requests
 
API_KEY = 'Basic YOUR_API_KEY'
 
# 1. Register and upload your file
file_res = requests.post('https://api.ffmpeg-api.com/file',
    headers={'Authorization': API_KEY, 'Content-Type': 'application/json'},
    json={'file_name': 'video.mov'}
).json()
 
with open('./video.mov', 'rb') as f:
    requests.put(file_res['upload']['url'], data=f)
print('Uploaded!')
 
# 2. Process with plain English
result = requests.post('https://api.ffmpeg-api.com/ai/ffmpeg/process',
    headers={'Authorization': API_KEY, 'Content-Type': 'application/json'},
    json={
        'inputs': [{'file_path': file_res['file']['file_path']}],
        'instructions': 'Convert to MP4, resize to 720p, good compression'
    }
).json()
 
print(result['result'][0]['download_url'])   # Your processed file
print(result['generated_command'])           # The FFmpeg command the AI created

Example instructions you can try

”Convert to MP4 with good quality"

"Extract audio as MP3"

"Resize to 720p and compress"

"Create a thumbnail at the 5 second mark"

"Trim from 30s to 1 minute"

"Convert WAV to AAC at 192kbps”

For the full guide on AI endpoints (including async processing and AI-powered metadata analysis), see AI Processing.

Full Control: FFmpeg Commands

If you know FFmpeg or need precise control over encoding options, use the standard endpoints with explicit FFmpeg parameters.

Process from URL

If your file is already hosted somewhere (S3, CDN, etc.), skip the upload step entirely:

curl -X POST https://api.ffmpeg-api.com/ffmpeg/process \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task": {
      "inputs": [{ "file_path": "https://download.blender.org/peach/bigbuckbunny_movies/BigBuckBunny_320x180.mp4" }],
      "outputs": [{ "file": "compressed.mp4", "options": ["-crf", "28"] }]
    }
  }'

The URL file is automatically imported and processed. You’ll get a download_url in the response.

💡

URL Requirements: Must be HTTPS and publicly accessible. Subject to same file size limits as uploads.

Upload → Process → Download

For local files, use the full workflow:

Complete JavaScript Example

Here’s the full workflow to convert a GIF to MP4:

import fs from 'fs'
 
const API_BASE = 'https://api.ffmpeg-api.com'
const API_KEY = 'Basic YOUR_API_KEY_HERE' // Get from dashboard
 
async function convertGifToMp4(gifPath) {
  try {
    // Step 1: Get upload URL
    const fileRes = await fetch(`${API_BASE}/file`, {
      method: 'POST',
      headers: {
        'Authorization': API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        file_name: 'input.gif'
      })
    })
 
    const fileData = await fileRes.json()
    console.log('✅ Got upload URL')
 
    // Step 2: Upload the GIF
    const gifBuffer = fs.readFileSync(gifPath)
    await fetch(fileData.upload.url, {
      method: 'PUT',
      body: gifBuffer,
      headers: {
        'Content-Type': 'image/gif'
      }
    })
    console.log('✅ File uploaded')
 
    // Optional: Verify uploaded file info (type, size)
    const infoRes = await fetch(`${API_BASE}/file/${fileData.file.file_path}`, {
      headers: { 'Authorization': API_KEY },
    })
    const info = await infoRes.json()
    console.log('ℹ️ File info:', info.file_info)
 
    // Step 3: Process with FFmpeg
    const processRes = await fetch(`${API_BASE}/ffmpeg/process`, {
      method: 'POST',
      headers: {
        'Authorization': API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        task: {
          inputs: [{
            file_path: fileData.file.file_path
          }],
          outputs: [{
            file: 'output.mp4',
            options: ['-crf', '23'] // Good quality
          }]
        }
      })
    })
 
    const result = await processRes.json()
    console.log('✅ Processing complete')
    console.log(`📊 Usage: ${result.usage.gb_sec} GB-seconds`)
 
    // Step 4: Download the result
    const downloadUrl = result.result[0].download_url
    const mp4Response = await fetch(downloadUrl)
    const mp4Buffer = Buffer.from(await mp4Response.arrayBuffer())
 
    fs.writeFileSync('output.mp4', mp4Buffer)
    console.log('✅ MP4 saved to output.mp4')
 
    return {
      downloadUrl,
      usage: result.usage,
      fileSize: result.result[0].size_bytes
    }
  } catch (error) {
    console.error('❌ Error:', error.message)
    throw error
  }
}
 
// Usage
convertGifToMp4('./my-animation.gif')
  .then(result => console.log('🎉 Conversion complete!', result))
  .catch(err => console.error('Failed:', err))

Key Points for JavaScript:

✅ Use fetch() for all HTTP requests
✅ Handle binary data with Buffer and ArrayBuffer
✅ Always check response status and handle errors
✅ The API key goes in the Authorization header

Complete Python Example

Here’s the full workflow using the requests library:

import requests
import os
 
API_BASE = 'https://api.ffmpeg-api.com'
API_KEY = 'Basic YOUR_API_KEY_HERE'  # Get from dashboard
 
def convert_gif_to_mp4(gif_path):
    """Convert a GIF file to MP4 using FFmpeg API"""
 
    headers = {
        'Authorization': API_KEY,
        'Content-Type': 'application/json'
    }
 
    try:
        # Step 1: Get upload URL
        file_response = requests.post(f'{API_BASE}/file',
            headers=headers,
            json={'file_name': 'input.gif'}
        )
        file_response.raise_for_status()
        file_data = file_response.json()
        print('✅ Got upload URL')
 
        # Step 2: Upload the GIF
        with open(gif_path, 'rb') as gif_file:
            upload_response = requests.put(
                file_data['upload']['url'],
                data=gif_file,
                headers={'Content-Type': 'image/gif'}
            )
            upload_response.raise_for_status()
        print('✅ File uploaded')
 
        # Step 3: Process with FFmpeg
        process_response = requests.post(f'{API_BASE}/ffmpeg/process',
            headers=headers,
            json={
                'task': {
                    'inputs': [{
                        'file_path': file_data['file']['file_path']
                    }],
                    'outputs': [{
                        'file': 'output.mp4',
                        'options': ['-crf', '23']  # Good quality
                    }]
                }
            }
        )
        process_response.raise_for_status()
        result = process_response.json()
        print('✅ Processing complete')
        print(f'📊 Usage: {result["usage"]["gb_sec"]} GB-seconds')
 
        # Step 4: Download the result
        download_url = result['result'][0]['download_url']
        mp4_response = requests.get(download_url)
        mp4_response.raise_for_status()
 
        with open('output.mp4', 'wb') as output_file:
            output_file.write(mp4_response.content)
        print('✅ MP4 saved to output.mp4')
 
        return {
            'download_url': download_url,
            'usage': result['usage'],
            'file_size': result['result'][0]['size_bytes']
        }
 
    except requests.exceptions.RequestException as e:
        print(f'❌ Error: {e}')
        raise
    except KeyError as e:
        print(f'❌ Unexpected response format: missing {e}')
        raise
 
# Usage
if __name__ == '__main__':
    try:
        result = convert_gif_to_mp4('./my-animation.gif')
        print('🎉 Conversion complete!', result)
    except Exception as e:
        print(f'Failed: {e}')

Key Points for Python:

✅ Use requests.json= for JSON payloads
✅ Always use raise_for_status() to catch HTTP errors
✅ Handle files with context managers (with open())
✅ Use binary mode (‘rb’, ‘wb’) for media files

Step-by-Step cURL Commands

1. Get Upload URL

curl -sS -X POST https://api.ffmpeg-api.com/file \
  -H 'Authorization: Basic YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"file_name":"input.gif"}'

Response:

{
  "ok": true,
  "file": {
    "file_path": "dir_abc123/input.gif",
    "file_name": "input.gif"
  },
  "upload": {
    "url": "https://storage.url/abc123...",
    "method": "PUT"
  }
}

Save these values:

UPLOAD_URL="<upload.url from response>"
FILE_PATH="<file.file_path from response>"

2. Upload Your GIF

curl -X PUT "$UPLOAD_URL" \
  --data-binary @./input.gif \
  -H "Content-Type: image/gif"

3. (Optional) Verify File Info

curl -sS -X GET "https://api.ffmpeg-api.com/file/dir_abc123/input.gif" \
  -H 'Authorization: Basic YOUR_API_KEY'

4. Process with FFmpeg

curl -sS -X POST https://api.ffmpeg-api.com/ffmpeg/process \
  -H 'Authorization: Basic YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d "{\"task\":{\"inputs\":[{\"file_path\":\"$FILE_PATH\"}],\"outputs\":[{\"file\":\"output.mp4\",\"options\":[\"-crf\",\"23\"]}]}}"

Response:

{
  "ok": true,
  "result": [{
    "file_name": "output.mp4",
    "size_bytes": 1234567,
    "download_url": "https://download.url/output.mp4"
  }],
  "usage": {
    "gb_sec": 0.45,
    "time_sec": 3.2
  }
}

5. Download Result

DOWNLOAD_URL="<download_url from response>"
curl -o output.mp4 "$DOWNLOAD_URL"

Understanding the Response

When processing completes (via AI or standard endpoints), you’ll get detailed information:

Response Breakdown

result[0].download_url → Direct link to your processed file

result[0].size_bytes → Output file size in bytes

usage.gb_sec → Billing units consumed (see pricing)

usage.time_sec → Processing time in seconds

generated_command → (AI endpoints only) The FFmpeg task the AI created from your instructions

Common Variations (Standard Endpoints)

🎬 Resize Video

Change the output options to resize your video:

{
"task": {
  "outputs": [{
    "file": "resized.mp4",
    "options": ["-vf", "scale=1280:720", "-crf", "23"]
  }]
}
}

🎵 Extract Audio

Pull audio track from a video:

{
"task": {
  "outputs": [{
    "file": "audio.mp3",
    "options": ["-vn", "-acodec", "mp3"]
  }]
}
}

⏱️ Trim Video

Start at 30 seconds, take 60 seconds:

{
"task": {
  "inputs": [{
    "file_path": "your-file-path",
    "options": ["-ss", "30", "-t", "60"]
  }]
}
}

💡

Pro Tip: Once uploaded, files stay available for reuse in multiple processing tasks. Upload once, process many times with different settings!

Troubleshooting

❌ “Invalid API key” (401 error)

Check that your API key:

Starts with “Basic ” (note the space)
Is copied exactly from the Dashboard
Is in the Authorization header, not the body

❌ “File not found” during processing

Make sure you:

Used the exact file_path from the upload response
Successfully uploaded to the upload.url first
Didn’t modify the file path string

❌ Upload fails with 403/403 error

Upload URLs expire after ~5 minutes. If you get errors:

Get a fresh upload URL from /file
Upload immediately after getting the URL
Don’t store upload URLs for later use

Overview Authentication

Get Started in 5 Minutes

Easiest: AI Processing (Beta)

Full Control: FFmpeg Commands

Before you start

Easiest: AI Processing

Process from a URL

Process an uploaded file

Example instructions you can try

Full Control: FFmpeg Commands

Process from URL

Upload → Process → Download

Complete JavaScript Example

Key Points for JavaScript:

Complete Python Example

Key Points for Python:

Step-by-Step cURL Commands

1. Get Upload URL

2. Upload Your GIF

3. (Optional) Verify File Info

4. Process with FFmpeg

5. Download Result

Understanding the Response

Common Variations (Standard Endpoints)

🎬 Resize Video

🎵 Extract Audio

⏱️ Trim Video

Troubleshooting

What’s Next?

🤖 AI Processing

⚡ Advanced Processing

📁 Organize Your Files

📖 Code Examples