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 {{input.mp4}} -t 5 {{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.

File Templating

Use template markers to reference files within your commands. Both {{key}} and <<key>> are supported. The API automatically handles downloading inputs to the local worker and uploading outputs once the command completes.

Use <<key>> in tools where {{key}} has its own meaning, such as Make.

Mapping Inputs

Reference keys defined in the input_files object.

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

Referencing Outputs

Reference filenames defined in the output_files list.

{
  "output_files": ["thumbnail.jpg", "preview.mp4"],
  "ffmpeg_commands": [
    "-i {{input}} -ss 00:00:01 -vframes 1 {{thumbnail.jpg}}",
    "-i {{input}} -t 10 {{preview.mp4}}"
  ]
}

Variables in Filters

You can use templates anywhere in the command string, including inside complex filter definitions.

{
  "input_files": { "logo": "https://example.com/watermark.png" },
  "ffmpeg_commands": [
    "-i {{input}} -i {{logo}} -filter_complex '[0:v][1:v]overlay=W-w-10:H-h-10' {{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.