🤖 AI Chat is here! Try it out →
API DocsQuick Start

Get Started in 5 Minutes

Transform your first video file with FFmpeg API. This guide walks through the complete workflow: upload → process → download. You’ll convert a GIF to MP4, but the same pattern works for any media transformation.

Before you start

Get your API key from the Dashboard.

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

Understanding the Response

When processing completes, 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

Common Variations

🎬 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

What’s Next?

📁 Organize Your Files

Learn to create directories and manage multiple files efficiently.

⚡ Advanced Processing

Explore complex FFmpeg operations, filters, and multi-file workflows.

🔗 n8n Automation

Build no-code video workflows with drag-and-drop automation.

Questions? Check out our Examples for more code samples or browse the API Reference for complete endpoint documentation.

OverviewAuthentication