---
name: logicboostkit-media
description: Use when you need to run FFmpeg or ffprobe on video, audio or image files over HTTP: transcode, compress, trim, make thumbnails or GIFs, extract audio, burn subtitles, add a watermark, resize, or read metadata, with LogicBoostKit Media's API.
---

# LogicBoostKit Media

## What it is

An HTTP API that runs FFmpeg and ffprobe on your files. You send a task as JSON: inputs, outputs and FFmpeg's own options. The API runs it and answers with download URLs for the outputs, the job's usage and its price.

## When to use it

- A user wants a media file converted, compressed, trimmed, resized, captioned, watermarked, turned into a GIF or a thumbnail, or its audio extracted.
- A user wants a media file's duration, codecs, resolution or frame rate.
- You can't, or shouldn't, run FFmpeg locally.

Don't use it for files the user is not allowed to process, or for anything the acceptable use policy forbids: https://media.logicboostkit.com/acceptable-use

## Base URL and authentication

- Base URL: https://media.logicboostkit.com
- Every request carries `Authorization: Basic <key>`. The user creates a key in the console after signing up and adding a card (https://media.logicboostkit.com/sign-up). Never print the key; read it from the environment (the docs use `$MEDIA_KEY`).
- Requests and responses are JSON. Files travel separately, to and from signed URLs.

## The task

```json
{
  "task": {
    "inputs": [{ "file_path": "dir_.../source.mp4", "options": ["-ss", "5"] }],
    "outputs": [{ "file": "output.mp4", "options": ["-c:v", "libx264", "-crf", "23"], "maps": ["0:v", "0:a"] }],
    "filter_complex": "optional filter graph across inputs"
  }
}
```

- `inputs`: 1 to 100. Each `file_path` is `dir_id/file_name` of an uploaded file, or a public HTTPS URL. Uploaded inputs must all be in one directory.
- `outputs`: 1 to 50. Each `file` is a name, different from every input's. A numbered pattern such as `frame_%03d.png` returns every file it produces.
- `options` are FFmpeg's own, as separate strings: `["-crf", "23"]`, never `["-crf 23"]`. Every entry is an option or the one value that follows it.
- Inputs from one directory share the job's folder, so a filter can name another input by its file name (`subtitles=subtitles.srt`).

## Upload and download

1. `POST https://media.logicboostkit.com/file` with `{"file_name": "source.mp4"}` (and `dir_id` to add to an existing directory). The answer has `file.file_path` and `upload.url`.
2. `PUT` the bytes to `upload.url` within 5 minutes.
3. Use `file.file_path` as an input.
4. Each `result[]` entry has a `download_url`, valid for 1 hour. `GET https://media.logicboostkit.com/file/download/{dirId}/{fileName}` gives a fresh one.

A directory and its files are deleted 24 hours after it is created (`POST /directory` with `ttl` sets up to 7 days). Download what you need before then. To skip the upload, give a public HTTPS URL as the input's `file_path`.

## Sync or async

- `POST https://media.logicboostkit.com/ffmpeg/process` waits and answers with `result`, `usage`, `request_id` and `amount_usd`. Use it for short jobs.
- `POST https://media.logicboostkit.com/ffmpeg/process/async` answers `202` at once with `job_id`. Poll `GET https://media.logicboostkit.com/job/{jobId}` until `status` is `completed`, `failed` or `cancelled`, or pass `webhook_url` (public HTTPS) to receive the same body by POST. Use it for anything that may take more than a minute or two. A job may run for up to 60 min.
- A webhook is retried up to 6 times over about 2 hours. The result stays readable from `GET /job/{jobId}` either way.

## ffprobe

`POST https://media.logicboostkit.com/ffprobe/analyze` with `{"file_path": "...", "probe": {"format": ["duration", "size", "bit_rate"], "streams": ["codec_type", "codec_name", "width", "height", "r_frame_rate"]}}`. Leave out `probe` for everything. The answer's `result` is ffprobe's JSON; like ffprobe, it reports most numbers as strings.

## Limits

- 5 GB per file; 100 inputs and 50 outputs per task.
- 300 requests a minute per key; 50 jobs at once per account.
- 60 min per job.

## Pricing

USD 0.01332 per GB-second: (input GB + output GB) × processing seconds. Only processing and probe requests that succeed are charged. Failed, rejected, rate-limited, timed-out and cancelled requests, and file and directory calls, cost nothing. Every successful response states `usage.gb_sec` and `amount_usd`; tell the user what a job cost when it matters to them.

## Errors

Every error is `{"ok": false, "error": "..."}` with a status code:

- `400`: the request is wrong as sent. Read `error`, fix the task, send again.
- `401`: no key, or an invalid, revoked or expired key. `403`: the account isn't active; `error` says what the user must do.
- `404`: the directory, file or job isn't there, or has expired.
- `409`: a name already uploaded, or a job that can no longer be cancelled.
- `429` and `503`: wait for `Retry-After` seconds, then send the same request again.
- `500`: FFmpeg failed (the same task will fail again: fix its options) or something broke on our side (retry once).

## Refused options

These are refused with a `400`, because they read or write files, or reach the network, outside the task:

- Options: -i, -protocol_whitelist, -protocol_blacklist, -attach, -dump_attachment, -dump, -hex, -filter_script, -filter_complex_script, -progress, -report, -sdp_file, -vstats, -vstats_file, -stdin, -safe, -enable_drefs, -use_absolute_path, -allowed_extensions, -allowed_segment_extensions, -extension_picky, -listen, -listen_timeout, -format_whitelist, -codec_whitelist, -/option, --
- Options that print and exit: -L, -license, -h, -help, -version, -buildconf, -formats, -muxers, -demuxers, -devices, -codecs, -decoders, -encoders, -bsfs, -protocols, -filters, -pix_fmts, -layouts, -sample_fmts, -dispositions, -colors, -sources, -sinks, -hwaccels
- Formats: concat, lavfi, tee, fifo, and capture devices
- Filters: movie, amovie, zmq, azmq, sendcmd, asendcmd, frei0r, frei0r_src, ladspa, lv2
- URLs, absolute paths and `..` inside options or filters; playlists and manifests (HLS, DASH) as inputs.

## Before you send a job

- [ ] The key comes from the environment, and the request uses `Authorization: Basic <key>`.
- [ ] Every input is uploaded (or is a public HTTPS URL), and uploaded inputs share one directory.
- [ ] Each output's name differs from every input's, and its extension matches the format you want.
- [ ] Options are split into separate strings, and none is refused.
- [ ] Long job? Use the async endpoint, with a webhook or polling.
- [ ] You will download the outputs within 1 hour, or ask for a fresh URL.

## More

- Docs: https://media.logicboostkit.com/docs
- OpenAPI: https://media.logicboostkit.com/openapi.json
- Index for agents: https://media.logicboostkit.com/llms.txt