Processing

Use POST /ffmpeg/process to run FFmpeg tasks using previously uploaded files.

Request

POST https://api.ffmpeg-api.com/ffmpeg/process
Authorization: Basic <YOUR_API_KEY>
Content-Type: application/json
 
{
  "task": {
    "inputs": [
      { "file_path": "<file_path>", "options": ["-ss", "10"] }
    ],
    "outputs": [
      { "file": "output.mp4", "options": ["-c:v", "libx264", "-crf", "23"] }
    ],
    "filter_complex": "[0:v]scale=1280:720[out]"
  }
}

Task shape

inputs[]: array of inputs
- file_path (required): <file_path> from the /file response
- options[] (optional): array of strings applied before the input
outputs[]: array of outputs
- file (required): output filename (must not conflict with input filenames)
- options[] (optional): array of FFmpeg options
- maps[] (optional): map streams or labeled filter outputs
filter_complex (optional): filter graph string

⚠️

All inputs must belong to the same directory. Output filenames must not conflict with existing input filenames.

Response

{
  "ok": true,
  "result": [
    {
      "file_name": "output.mp4",
      "size_bytes": 1234567,
      "download_url": "https://..."
    }
  ],
  "usage": {
    "time_sec": 12.5,
    "input_size_gb": 0.098,
    "output_size_gb": 0.015,
    "gb_sec": 1.4125
  }
}

Errors

400: invalid JSON, missing task, invalid file_path, filename conflict, mixed directories
401: invalid API key
403: quota exceeded, unauthorized directory access
404: directory or file not found
500: FFmpeg failure or parsing error

Examples

{
  "task": {
    "inputs": [
      { "file_path": "dir_123/video.mp4" },
      { "file_path": "dir_123/audio.m4a" }
    ],
    "outputs": [
      { "file": "muxed.mp4", "options": ["-c:v", "copy", "-c:a", "aac"] }
    ]
  }
}

{
  "task": {
    "inputs": [
      { "file_path": "dir_123/left.mp4" },
      { "file_path": "dir_123/right.mp4" }
    ],
    "filter_complex": "[0:v]scale=960:540[l];[1:v]scale=960:540[r];[l][r]hstack[out]",
    "outputs": [
      {
        "file": "side_by_side.mp4",
        "options": ["-c:v", "libx264"],
        "maps": ["[out]"]
      }
    ]
  }
}

See Examples for complete client scripts.

File Management Migration Guide