ffprobe API: Get Video Metadata from a URL

To get video metadata from a URL without installing ffprobe, send a probe job to the Xora API: { "mode": "probe", "input": { "url": "..." } }. When the job completes, it returns the raw ffprobe JSON plus ready fields such as durationSeconds, width, height, videoCodec and hasAudio.

This guide shows the local ffprobe commands, the same check as an API call, and how to use the result to pick the next FFmpeg command. For other common commands, see the FFmpeg cheat sheet.

The local command

ffprobe -v error -show_format -show_streams -of json "https://example.com/video.mp4"

Flag	What it does
`-v error`	Print only errors, not the banner and build information.
`-show_format`	Container facts: duration, size, overall bitrate, format name.
`-show_streams`	One entry per stream: codec, resolution, frame rate, pixel format, sample rate, channels.
`-of json`	Write the result as JSON, so a script can read it.

To get one value only, use -show_entries:

# Duration in seconds
ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 video.mp4

# Width, height and codec of the first video stream
ffprobe -v error -select_streams v:0 -show_entries stream=width,height,codec_name -of csv=p=0 video.mp4

The same check with the Xora API

curl -X POST https://api.xora.sh/v1/jobs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "probe",
    "input": { "url": "https://example.com/video.mp4" },
    "stageInput": false
  }'

The response is { id, state }. Poll GET /v1/jobs/{id}, or pass webhookUrl, until the state is completed. Then read the probe object:

{
  "state": "completed",
  "mode": "probe",
  "probe": {
    "hasVideo": true,
    "hasAudio": true,
    "durationSeconds": 125.4,
    "width": 1920,
    "height": 1080,
    "videoCodec": "h264",
    "audioCodec": "aac",
    "format": { "duration": "125.400000", "bit_rate": "4500000" },
    "streams": []
  }
}

A probe job writes no output file. The metadata is on the job record under probe, not under output. stageInput: false lets ffprobe read only the byte ranges it needs when the server supports them; see input staging. For a file on your own machine, get an uploadId from POST /v1/uploads and send it in place of the URL. See the probe reference.

What to do with the result

The usual reason to probe is to pick the next command. Some examples:

Probe result	Next step
`videoCodec` is `h264`, `audioCodec` is `aac`	Remux only: convert MOV to MP4 with `-c copy`.
`videoCodec` is `hevc` or `prores`	Re-encode to H.264 for browsers, or use the webReady recipe.
`hasAudio` is `false`	Do not use `-c:a copy` or the `extractAudio` recipe.
`height` is greater than `width`	The video is portrait. Scale with `scale=-2:1280`, not a landscape size.
`durationSeconds` is over your limit	Reject the upload, or trim it.

Agents use the same pattern: probe first, then write the command. See LLMs write good FFmpeg commands.

Common errors

Error	Cause	Fix
`Invalid data found when processing input`	The URL returns an HTML page or an error, not media.	Open the URL and check that it returns the file. Signed URLs can expire.
`moov atom not found`	The MP4 is incomplete, or its index is at the end and the download stopped.	Check the source file. Re-upload it if the upload did not finish.
`VALIDATION_ERROR` (Xora)	The body has fields a probe job does not accept, such as `output` or `recipe`.	Send only `mode`, `input`, and optionally `stageInput` and `webhookUrl`.
The `probe` field is empty	The job is not `completed` yet.	Poll until the state is terminal.

Failed and rejected Xora jobs cost nothing. See error handling.

Probe reference.
FFmpeg cheat sheet: the common commands, each as an API call.
Generate video thumbnails from a URL.

Frequently asked questions

Is there an API for ffprobe?

Yes. Send a job with mode probe and the video URL to the Xora API. When the job completes, the job record has a probe object with the raw ffprobe output (format, streams, chapters, programs) and flags such as hasAudio, durationSeconds, width, height and videoCodec.

How do I get the duration of a video from a URL?

Locally: ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 followed by the URL. With Xora, run a probe job and read probe.durationSeconds.

Does a probe job download the whole file?

Not when the server supports HTTP range requests and you set stageInput to false. ffprobe then reads the container header and the parts it needs. Without range support, Xora copies the file first and the job still completes.

How do I check if a video has an audio track?

Read probe.hasAudio on the completed Xora job. Locally, run ffprobe -v error -select_streams a -show_entries stream=index -of csv=p=0 on the file; an empty result means there is no audio stream.