Running Commands

Submit a Job

Use POST https://verygoodffmpeg.com/api/ffmpeg with your API key and a JSON body.

For complete schema details, use the API Reference.

Request

POST /api/ffmpeg HTTP/1.1
Authorization: Bearer REPLACE_BEARER_TOKEN
Content-Type: application/json
Host: verygoodffmpeg.com

{
  "input_files": {
    "input.mp4": "https://storage.verygoodffmpeg.com/sample.mp4"
  },
  "output_files": [
    "output.mp4"
  ],
  "ffmpeg_commands": [
    "-i inputs/input.mp4 -t 5 outputs/output.mp4"
  ],
  "webhook_url": "https://example.com/webhooks/ffmpeg",
  "machine": "cpu",
  "timeout_seconds": 300
}

Response

{
  "data": {
    "id": "8f3c2b6a-4d9e-4f0c-9b5a-2d3e4f5a6b7c",
    "status": "queued",
    "output_files": {},
    "error_message": ""
  }
}

Save the job id. Use it to poll status and download outputs.

Input and Output Files

Every job runs in a workspace with two directories: inputs and outputs.

Before your commands run, each URL in input_files is downloaded into inputs under its key name. After your commands finish, every file in outputs named in output_files is uploaded and returned as a download URL.

Reference files by path: inputs/your-file.mp4 to read, outputs/your-file.mp4 to write.

Reading Inputs

The keys of input_files are the file names inside inputs.

{
  "input_files": {
    "background.mp4": "https://example.com/background.mp4",
    "overlay.png": "https://example.com/logo.png"
  },
  "output_files": ["output.mp4"],
  "ffmpeg_commands": [
    "-i inputs/background.mp4 -i inputs/overlay.png -filter_complex 'overlay=10:10' outputs/output.mp4"
  ]
}

Writing Outputs

Write to outputs/ using the names listed in output_files.

{
  "input_files": { "input.mp4": "https://example.com/video.mp4" },
  "output_files": ["thumbnail.jpg", "preview.mp4"],
  "ffmpeg_commands": [
    "-i inputs/input.mp4 -ss 00:00:01 -vframes 1 outputs/thumbnail.jpg",
    "-i inputs/input.mp4 -t 10 outputs/preview.mp4"
  ]
}

A file written to outputs that is not listed in output_files is not uploaded.

Paths in Filters

Paths work anywhere in the command string, including inside complex filter definitions.

{
  "input_files": {
    "input.mp4": "https://example.com/video.mp4",
    "logo.png": "https://example.com/watermark.png"
  },
  "output_files": ["output.mp4"],
  "ffmpeg_commands": [
    "-i inputs/input.mp4 -i inputs/logo.png -filter_complex '[0:v][1:v]overlay=W-w-10:H-h-10' outputs/output.mp4"
  ]
}

Tracking Job Status

To check the status of a job manually, use the GET /api/jobs/{id} endpoint.

GET /api/jobs/{id} HTTP/1.1
Authorization: Bearer REPLACE_BEARER_TOKEN
Host: verygoodffmpeg.com

Use Jobs for status values, wait mode, and output URLs.

Billing

Jobs are billed by processed GB: input bytes read plus output bytes written. Failed and cancelled jobs are billed for the bytes processed before they stop. Webhook payloads and intermediate temp files do not add to your bill.