Reference · Processing

POST/ffmpeg/process/async

Queues one task and answers at once with a job_id. Read the result from GET /job/{jobId}, or have it sent to a webhook. The task is checked, and URL inputs are fetched, before the answer.

Request body

Request body
task	object	Required. What to run.
task.inputs[]	array	Required. The files to read, in order: 1 to 100. Each input is one file.
inputs[].file_path	string	Required. dir_id/file_name of an uploaded file, or a public HTTPS URL. Uploaded inputs must all be in one directory.
inputs[].options[]	string[]	FFmpeg options placed before this input.
task.outputs[]	array	Required. The files to write: 1 to 50.
outputs[].file	string	Required. The output’s file name. It must differ from every input’s name and from the other outputs. A numbered pattern such as `frame_%03d.png` returns every file it produces.
outputs[].options[]	string[]	FFmpeg options for this output.
outputs[].maps[]	string[]	Streams to map into this output, each passed as `-map`.
task.filter_complex	string	A filter graph across the inputs.
task.output_dir_id	string	Where the outputs go. By default the inputs’ directory, or a new one when every input is a URL.
webhook_url	string	A public HTTPS URL to send the result to. See Webhooks.

Some options and filters are refused; see Options and filters we refuse. A URL input is fetched into the outputs’ directory before the task runs, and stays there until the directory expires.

Example

Request

curl https://media.logicboostkit.com/ffmpeg/process/async \
  -H "Authorization: Basic $MEDIA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task": {
      "inputs": [{ "file_path": "dir_pi23jgy1yxlmigi873bz/source.mp4" }],
      "outputs": [{ "file": "source-720p.mp4", "options": ["-vf", "scale=-2:720", "-crf", "23"] }]
    },
    "webhook_url": "https://example.com/hooks/media"
  }'

Response

HTTP/1.1 202 Accepted
X-Request-Id: job_0mv6ihz6vfx5ua0h05x8bmql

{
  "ok": true,
  "job_id": "job_0mv6ihz6vfx5ua0h05x8bmql",
  "status": "pending",
  "request_id": "job_0mv6ihz6vfx5ua0h05x8bmql"
}

Response fields

Response fields
ok	boolean	true when the job was queued.
job_id	string	The job’s id: job_ and 24 lower-case letters and digits.
status	string	Always pending.
request_id	string	The same value as job_id, also sent as the X-Request-Id header.

Status codes

Status codes
202	The job is queued. Nothing is charged until it completes.
400	The body or the task is malformed, a name breaks the naming rules, an option or filter is refused, an input is a playlist or manifest, a URL input could not be fetched, or webhook_url isn’t a public HTTPS URL.
401	The `Authorization` header is missing, or the key is invalid, revoked or expired.
403	The account isn’t active, or a file is over 5 GB. The error says what to do.
404	`Directory not found` or `File not found in directory`: an input or the output directory isn’t in your account, or has expired.
429	More than 300 requests in a minute on this key, or 50 of the account’s jobs already in progress. Wait for the number of seconds in `Retry-After`.

Every error has the shape {"ok": false, "error": "…"} and is never charged.

Webhooks

With a webhook_url, the job’s result is sent to it as a POST with a JSON body when the job completes or fails. A cancelled job sends nothing. The request carries Content-Type: application/json and the job’s id as X-Request-Id.

Completed

{
  "job_id": "job_0mv6ihz6vfx5ua0h05x8bmql",
  "status": "completed",
  "result": [
    {
      "file_name": "source-720p.mp4",
      "size_bytes": 412316860,
      "download_url": "https://…"
    }
  ],
  "usage": {
    "time_sec": 41.27,
    "input_size_gb": 1.804199982,
    "output_size_gb": 0.384,
    "gb_sec": 90.307013221
  },
  "request_id": "job_0mv6ihz6vfx5ua0h05x8bmql",
  "amount_usd": 1.202889416
}

Failed

{
  "job_id": "job_0mv6ihz6vfx5ua0h05x8bmql",
  "status": "failed",
  "error": "FFmpeg command failed with exit code 1: Conversion failed!",
  "request_id": "job_0mv6ihz6vfx5ua0h05x8bmql"
}

The URL

It must be HTTPS, without a user name or password in it.
It must be public. Private, local and other special-purpose addresses are refused, by the address written and by what the name resolves to.
It is checked when you submit the job, and again at each delivery.

Delivery

Any 2xx answer within 10 seconds counts as delivered. Redirects are not followed.
Anything else is tried again: up to 6 attempts over about 2 hours.
After delivery, or after the last attempt, we forget the URL.
A completed job is charged whether or not its webhook can be delivered. Its result stays readable from GET /job/{jobId}.