-filter_complex is Not Supported

If you tried to pass -filter_complex in your transcode job and got a 400 error, this article explains why — and how to achieve the same result with options we do support.

The Error

{
  "error": "Invalid FFmpeg options",
  "details": [
    "The option -filter_complex is not supported for security and resource reasons."
  ]
}

Why It's Blocked

filter_complex graphs can reference filters that read arbitrary files from disk (movie=), execute commands (sendcmd), or evaluate arbitrary expressions (aevalsrc, geq). Allowing raw -filter_complex strings would give every API caller a way to reach past the sandbox. It can also construct arbitrarily expensive filter graphs that tie up workers.

Almost every common use of -filter_complex has a safer, simpler alternative in our API.

What to Use Instead

Single-input video filters → -vf

Scaling, cropping, padding, drawtext, simple overlays on a single input — use -vf.

#### ❌ Blocked

{
  "options": [
    { "option": "-filter_complex", "argument": "[0:v]scale=1280:720[v]" }
  ]
}

#### ✅ Supported

{
  "options": [
    { "option": "-vf", "argument": "scale=1280:720" }
  ]
}

Single-input audio filters → -af

Volume, fade, resample on a single input — use -af.

#### ✅ Supported

{
  "options": [
    { "option": "-af", "argument": "volume=0.5" }
  ]
}

Text overlays → @text-overlay virtual option

Instead of hand-writing drawtext or ASS filter graphs, use the @text-overlay virtual option. It handles positioning, styling, and wrapping for you.

#### ✅ Supported

{
  "inputs": [
    { "url": "gs://your-bucket/clip.mp4" }
  ],
  "outputFormat": "mp4",
  "options": [
    {
      "option": "@text-overlay",
      "argument": {
        "text": "Hello world!",
        "style": { "position": "center", "fontSize": 60 }
      }
    }
  ]
}

See virtual options for the full list of high-level effects.

Multi-input operations → filters array

For overlays, watermarks, and other multi-input operations, use the top-level filters array alongside multiple inputs.

#### ✅ Supported

{
  "inputs": [
    { "url": "gs://your-bucket/video.mp4" },
    { "url": "gs://your-bucket/watermark.png" }
  ],
  "outputFormat": "mp4",
  "filters": [
    { "filter": "overlay=W-w-10:H-h-10" }
  ]
}

Quick Reference

Still Need -filter_complex?

If your workflow genuinely can't be expressed with the options above, we want to hear about it. Send us the filter graph you're trying to run and what you're trying to achieve:

We regularly add new virtual options based on real requests.