API reference

Base URL

https://ffmpeg-api.way.srl/api

Authentication

Authorization: Bearer <api_key>

Every request needs an API key from your dashboard, sent as a bearer token. All responses are JSON and wrap the payload in a data field.

Endpoints

POST /ffmpeg Run FFmpeg commands

Submit one or more FFmpeg commands to run on the fleet. Reference inputs and outputs from your commands with {{name}} placeholders.

Query parameters

Name	Type		Description
wait	boolean	optional	Wait for the job to finish before responding. Defaults to `false`.

Request body

Field	Type		Description
input_files	object	required	Map of file name → source URL. Names may use letters, numbers, `_ - .`
output_files	string[]	required	Output names or glob patterns. A literal name must match a placeholder in your commands; a glob such as `seg_.ts` or `frame_.png` captures a variable set of files that FFmpeg produces, so you don't need to know the names in advance.
ffmpeg_commands	string[]	required	FFmpeg command strings. Use `{{key}}` or `<<key>>` to reference input/output names.
machine	string	optional	`cpu` (default) or `nvidia` for CUDA filters/encoders.
timeout_seconds	integer	optional	Execution timeout. Defaults to 300s, may be raised up to 6 hours (21600).
webhook_url	string	optional	URL called when the job completes or fails.

Example

curl -X POST https://ffmpeg-api.way.srl/api/ffmpeg \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input_files": { "input.mp4": "https://example.com/sample.mp4" },
    "output_files": ["seg_*.ts", "playlist.m3u8"],
    "ffmpeg_commands": [
      "-i {{input.mp4}} -c:v libx264 -hls_time 6 -hls_segment_filename seg_%03d.ts -f hls {{playlist.m3u8}}"
    ]
  }'

GET /jobs List jobs

List jobs in your account, newest first. Supports limit (1–200, default 50) and offset query parameters. Returns data (array of jobs) and pagingParams.

curl https://ffmpeg-api.way.srl/api/jobs?limit=20 \
  -H "Authorization: Bearer $API_KEY"

GET /jobs/{id} Get a job

Fetch a single job by ID. Submit with ?wait=false and poll this endpoint: progress (0-100) updates ~1/s while running, alongside speed, fps and eta_seconds. When status is succeeded, output_files holds presigned download URLs.

curl https://ffmpeg-api.way.srl/api/jobs/job_abc123 \
  -H "Authorization: Bearer $API_KEY"

POST /jobs/{id}/cancel Cancel a job

Cancel a queued or running job.

curl -X POST https://ffmpeg-api.way.srl/api/jobs/job_abc123/cancel \
  -H "Authorization: Bearer $API_KEY"

POST /tmp-file Prepare a file upload

Get a presigned upload_url and download_url pair for temporary storage. Upload a local file to upload_url, then pass download_url as an entry in input_files.

curl -X POST https://ffmpeg-api.way.srl/api/tmp-file \
  -H "Authorization: Bearer $API_KEY"

The job object

Field	Type	Description
id	string	Unique job identifier.
status	string	`queued`, `running`, `succeeded`, `failed`, or `cancelled`.
progress	number \| null	Overall completion percentage (0-100), updated ~once/second while running. Null until known (queued, or media duration not yet determined); 100 on success. Poll this endpoint to drive a progress bar.
speed	number \| null	Encoding speed as a multiple of realtime (e.g. 2.5 = 2.5×). Present while running.
fps	number \| null	Frames per second currently being processed.
eta_seconds	number \| null	Estimated seconds remaining for the current command.
command_index	number \| null	Zero-based index of the command running (for multi-command jobs like 2-pass or HLS).
commands_total	number \| null	Total number of ffmpeg commands in the job.
ffmpeg_commands	string[]	The commands that were submitted.
input_files	object	Named input URLs that were provided.
output_files	object	Presigned download URLs keyed by the concrete file names produced. Glob patterns from the request are expanded to the actual files. Empty until the job succeeds.
queued_at	string	ISO 8601 timestamp when the job entered the queue.
started_at	string \| null	When the job started running.
finished_at	string \| null	When the job finished.
error_message	string	Error text if the job failed; empty otherwise.
timeout_seconds	number \| null	Execution timeout applied to this job.
total_input_bytes	number \| null	Total size of all inputs; null until finished.
total_output_bytes	number \| null	Total size of all outputs; null until finished.
webhook_url	string \| null	Webhook notified on completion.