Jobs

Use jobs to track FFmpeg work after you submit a request.

Status Values

• queued: the job is waiting for a worker.
• running: the worker is running commands.
• succeeded: all commands finished and outputs are ready.
• failed: the job could not finish.
• cancelled: the job was stopped.

succeeded, failed, and cancelled are terminal states.

Poll a Job

Use GET /api/jobs/{id} to check status.

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

Response

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

output_files is empty until the job succeeds.

{
  "data": {
    "id": "8f3c2b6a-4d9e-4f0c-9b5a-2d3e4f5a6b7c",
    "status": "succeeded",
    "output_files": {
      "output.mp4": "https://storage.example.com/output.mp4"
    },
    "error_message": ""
  }
}

Output download URLs are signed URLs. Signed URLs last 7 days. Output files are retained for 30 days.

Wait Mode

Add ?wait=true to block the create request until the job finishes.

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"
}

Wait mode cancels the job if it does not finish within 15 minutes. Use normal async polling for long jobs.

Failed Jobs

When a job fails, check error_message.

{
  "data": {
    "status": "failed",
    "error_message": "ffmpeg exited with code 1"
  }
}