Reference · Processing

# POST/ffmpeg/process/async

Queues one task and answers at once with a `job_id`. Read the result from [GET /job/{jobId}](https://media.logicboostkit.com/docs/get-job), 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](#webhooks).

Some options and filters are refused; see [Options and filters we refuse](https://media.logicboostkit.com/docs/refused-options). A URL input is fetched into the outputs’ directory before the task runs, and stays there until the directory expires.

## Example

Request

```bash
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
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

```json
{
  "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

```json
{
  "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}](https://media.logicboostkit.com/docs/get-job).