Reference · Probe

POST/ffprobe/analyze

Runs ffprobe on one file and returns what it reports as JSON. Name the sections you want in probe, each with the fields to return. A probe is charged like any other request that succeeds: on the file’s size, the result’s size and the seconds ffprobe ran.

Request body

Request body
file_path	string	Required. dir_id/file_name of an uploaded file, or a public HTTPS URL. A URL is copied in, probed and deleted when the request ends.
probe	object	What to report. Left out, the format and every stream, with all their fields.
probe.format[]	string[]	Fields of the container to return. An empty array means every field. Field names are letters, digits and underscores.
probe.streams[]	string[]	Fields of each stream.
probe.chapters[]	string[]	Fields of each chapter.
probe.programs[]	string[]	Fields of each program.
probe.frames[]	string[]	Fields of each frame. Needs select_streams, and reads at most 30 seconds or 3000 frames.
probe.packets[]	string[]	Fields of each packet. The same conditions as frames.
probe.error[]	string[]	Fields of the error ffprobe reports, if it reports one.
probe.select_streams	string	A stream specifier, such as v:0 or a. Required with frames or packets.
probe.read_intervals	string	Which parts to read, in ffprobe’s notation, such as 10%+5. With frames or packets, no interval may be longer than 30 seconds or 3000 frames; left out, the first 30 seconds are read.
probe.count_frames	boolean	Count the frames of each stream by decoding it.
probe.skip_frame	string	Frames the decoder may skip: none, default, noref, bidir, nokey, nointra or all.
probe.analyzeduration	number \| string	How much of the file to analyze, in seconds (10) or with a unit (“10s”, “500ms”). At most 60 seconds.
probe.probesize	number \| string	How many bytes to probe, as a number or with a unit (“10M”). At most 50 MB.

Example

Request

curl https://media.logicboostkit.com/ffprobe/analyze \
  -H "Authorization: Basic $MEDIA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_path": "dir_pi23jgy1yxlmigi873bz/source.mp4",
    "probe": {
      "format": ["duration", "size", "bit_rate"],
      "streams": ["codec_name", "width", "height"]
    }
  }'

Response

HTTP/1.1 200 OK
X-Request-Id: job_0mv6iygbcl43togsnvc4g2wc

{
  "ok": true,
  "result": {
    "streams": [
      {
        "codec_name": "h264",
        "width": 1920,
        "height": 1080
      },
      {
        "codec_name": "aac"
      }
    ],
    "format": {
      "duration": "634.533333",
      "size": "1937244979",
      "bit_rate": "24424185"
    }
  },
  "usage": {
    "time_sec": 0.31,
    "input_size_gb": 1.804199982,
    "output_size_gb": 1.49e-7,
    "gb_sec": 0.55930204
  },
  "request_id": "job_0mv6iygbcl43togsnvc4g2wc",
  "amount_usd": 0.007449903
}

Response fields

Response fields
ok	boolean	true when ffprobe finished.
result	object	ffprobe’s JSON: one member per section you asked for. As ffprobe does, it reports most numbers as strings.
usage.time_sec	number	The seconds ffprobe ran, measured on the reference machine.
usage.input_size_gb	number	The file’s size.
usage.output_size_gb	number	The size of result.
usage.gb_sec	number	What the request is charged on.
request_id	string	The request’s id, also sent as the X-Request-Id header.
amount_usd	number	What the request was charged, in USD.

Status codes

Status codes
200	ffprobe finished. Charged.
400	The body is malformed, file_path isn’t dir_id/file_name or a public HTTPS URL, the file is a playlist or manifest, a field name or a control is invalid, frames or packets were asked for without select_streams, or a limit above is exceeded.
401	The `Authorization` header is missing, or the key is invalid, revoked or expired.
403	The account isn’t active, or the file is over 5 GB. The error says what to do.
404	`Directory not found` or `File not found in directory`.
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`.
500	ffprobe failed, ran out of time, or the result was too large to return. Ask for fewer fields or a shorter interval. Not charged.
503	Too busy to start the probe now. Retry after the seconds in Retry-After.

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

Guides

Guides that use this endpoint
Read video metadata with ffprobe	Duration, codecs, resolution and frame rate, as JSON.