Getting started with the Probe API

We are currently in private beta. If you would like to join the program submit a request

Quickstart - Minimal request

curl -G https://api.probe.dev/v1/probe/file \
  --data-urlencode "token=${PROBE_API_TOKEN}" \
  --data-urlencode "only=ffprobe" \
  --data-urlencode "url=https://probelibrary.s3.amazonaws.com/sample-source.mp4"

The response is standard JSON identical to what a local ffprobe run would return.

Authentication

After registering, you'll see your PROBE_API TOKEN on the Authentication tab of these docs and every API request/response in the My Requests tab of these docs.

Endpoint

https://api.probe.dev/v1/probe/file

We accept GET and POST:

Provide the Media Asset

Specify a direct link to media file hosted on any webserver or within a publicly available S3 bucket. If you don't have a media asset handy, check out our sample media library which contains a broad and diverse set of popular as well as edge case codecs and containers.

{
    "url": "https://probelibrary.s3.amazonaws.com/sample-source.mp4"
}

Using Amazon S3 with Key Based Authorization

To use key-based authorization for a media asset specify your key and secret in the url path. For more information about setting up key based authorization visit AWS Identity and Access Management.

A direct http link with the KEY and SECRET included:

http://KEY:[email protected]/BUCKET/PATH
s3://KEY:SECRET@BUCKET/PATH

Using Amazon S3 with a Presigned URL

If your object is private, create a pre‑signed URL and pass it in the url field:

{
    "url": "https://my-bucket.s3.amazonaws.com/sample-video.mp4?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIOSFODNN7EXAMPLE%2F20250506%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20250506T121314Z&X-Amz-Expires=86400&X-Amz-SignedHeaders=host&X-Amz-Signature=9a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1"
}

The query string grants read‑only access to sample-video.mp4 for 24 hours (86 400 seconds).

Selecting Report Types

Enable one, several, or all of: mediainfo, ffprobe, probe_report.

{
    "url": "https://probeqa.s3.amazonaws.com/trusted_sources/video/sample-source.mp4",
  "inject_json": true,  
  "probe_report": {
        "enabled": true,
        "diff": true
    },
    "mediainfo": {
        "enabled": true
    },
    "ffprobe": {
        "enabled": true
    }
}

Report Type — MediaInfo

MediaInfo summarizes the most relevant technical and tag information. Use version to pin a specific release; latest always picks the newest build we host.

{
    "mediainfo": {
        "enabled": true,
        "version": "latest",
        "output": "JSON"
    }
}

You may pass any MediaInfo CLI flag in snake_case; names match the original tool.

Report Type — FFprobe

FFprobe offers deeper introspection than MediaInfo and integrates seamlessly with FFmpeg pipelines.

{
    "ffprobe": {
        "enabled": true,
        "version": "latest",
        "output_format": "json"
    }
}

We accept virtually all ffprobe options with the same names so refer to the ffprobe documentation for details.

Report Type — Probe Report

The probe_report parses, reconciles and canonicalizes the raw outputs from FFprobe and MediaInfo, then applies machine‑learning heuristics (trained on >1 billion assets) to correct inconsistencies and deliver a single, authoritative metadata set.

{
    "probe_report": {
        "enabled": true,
        "diff": true
    }
}

Report Type — Apple MediaStreamValidator

Apple's MediaStreamValidator checks the compliance of HTTP Live Streaming (HLS) media streams against Apple’s technical specifications. This report is useful for validating .m3u8 playlists and ensuring streams meet Apple’s delivery standards.

Note: mediastreamvalidator is slower than other tools and typically takes 12–15 seconds to complete. We recommend using it selectively during staging or pre-publish validation workflows.

Example

{
  "mediastreamvalidator": {
    "enabled": true,
    "timeout": 30,
    "queue_timeout": 10,
    "parse_playlist_only": true,
    "enable_cli_output": false
  },
  "inject_json": true,
  "url": "https://example.com/path/to/playlist.m3u8"
}

Parameters

inject_json is supported for this report, allowing you to receive a canonicalized metadata object alongside raw tool output.

Migrating from local commands to the Probe API

The PHP example below shows a one‑line swap: replace the local shell invocation with an HTTPS GET to the Probe API while keeping every ffprobe parameter intact.

PHP

// Local execution (be sure to escape vars in production)
exec(
    'ffprobe -i ' . escapeshellarg($url) .
    " -print_format json -probesize $probesize" .
    " -analyzeduration $analyzeduration -max_probe_packets $max_probe_packets" .
    ' -show_format -show_streams',
    $output
);

PHP

// Equivalent call through the Probe API
$token = getenv('PROBE_API_TOKEN');   // safer than hard‑coding

$query = http_build_query([
    'token'                      => $token,
    'url'                        => $url,
    'only'                       => 'ffprobe',
    'ffprobe[output_format]'     => 'json',
    'ffprobe[probesize]'         => $probesize,
    'ffprobe[analyzeduration]'   => $analyzeduration,
    'ffprobe[max_probe_packets]' => $max_probe_packets,
    'ffprobe[show_format]'       => 'true',
    'ffprobe[show_streams]'      => 'true',
]);

$response = file_get_contents("https://api.probe.dev/v1/probe/file?$query");
$output   = json_decode($response, true);   // handle errors in production

That's it—you've migrated the command to a secure HTTPS call while preserving every original ffprobe flag.