- Fundamentals
- Running Commands
Running Commands
How to structure requests and track job status.
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": "https://storage.verygoodffmpeg.com/sample.mp4"
},
"output_files": [
"output.mp4"
],
"ffmpeg_commands": [
"-i {{input}} -t 5 {{output.mp4}}"
],
"webhook_url": "https://example.com/webhooks/ffmpeg",
"machine": "cpu"
}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 double curly braces {{key}} to reference files within your commands. The API automatically handles downloading inputs to the local worker and uploading outputs once the command completes.
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}}"
]
}Sequential File Naming
When generating multiple outputs (like HLS segments or frame sequences), define the base pattern in output_files.
{
"output_files": ["frame_%03d.png"],
"ffmpeg_commands": ["-i {{input}} -vf fps=1 {{frame_%03d.png}}"]
}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.