ESC

Media Info

Probe a remote video or audio file and return its container format and per-stream metadata — codec, resolution, duration, bitrate, sample rate, and more. Uses ffprobe under the hood.

No transcoding is performed, so the probe is fast even for large files: only as much of the file as needed to read the headers is fetched.

Base URL

https://convert.toolkitapi.io

Endpoints

Method Endpoint Purpose
POST /v1/convert/media-info Probe a Base64 media file for metadata
GET /v1/convert/media-info Probe a media file at a public URL for metadata

Authentication is via the X-API-Key header (or Authorization: Bearer).

POST /v1/convert/media-info

Request body

Field Type Required Description
url string yes Public URL of the media file to probe

Response fields

Field Type Description
format string Container format name, e.g. mov,mp4,m4a,3gp,3g2,mj2
format_long_name string Human-readable container name
duration number Container duration in seconds
size integer File size in bytes
bitrate integer Overall bitrate in bits per second
streams array Per-stream metadata objects

Each object in streams[] includes:

Field Type Description
index integer Stream index in the container
type string video, audio, subtitle, or data
codec string Codec short name, e.g. h264, aac, vp9
duration number | null Stream duration in seconds
bitrate integer | null Stream bitrate in bits per second
width / height integer Video frame dimensions (video streams only)
fps number Video frame rate (video streams only)
sample_rate integer Audio sample rate in Hz (audio streams only)
channels integer Audio channel count (audio streams only)
language string | null Stream language tag

Example — curl

curl -X POST "https://convert.toolkitapi.io/v1/convert/media-info" \
  -H "X-API-Key: $CONVERT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/clip.mp4"}'

Response:

{
  "format": "mov,mp4,m4a,3gp,3g2,mj2",
  "format_long_name": "QuickTime / MOV",
  "duration": 42.5,
  "size": 18432127,
  "bitrate": 3469821,
  "streams": [
    {
      "index": 0,
      "type": "video",
      "codec": "h264",
      "width": 1920,
      "height": 1080,
      "fps": 29.97,
      "duration": 42.5
    },
    {
      "index": 1,
      "type": "audio",
      "codec": "aac",
      "channels": 2,
      "sample_rate": 48000
    }
  ]
}

Example — Python

import httpx

resp = httpx.post(
    "https://convert.toolkitapi.io/v1/convert/media-info",
    headers={"X-API-Key": CONVERT_API_KEY},
    json={"url": "https://example.com/clip.mp4"},
)
resp.raise_for_status()
info = resp.json()

print(f"Duration: {info['duration']:.1f}s")
video = next(s for s in info["streams"] if s["type"] == "video")
print(f"Resolution: {video['width']}x{video['height']} @ {video.get('fps')} fps")
print(f"Codec: {video['codec']}")

Example — JavaScript

const resp = await fetch("https://convert.toolkitapi.io/v1/convert/media-info", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.CONVERT_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ url: "https://example.com/clip.mp4" }),
});
const info = await resp.json();

const video = info.streams.find((s) => s.type === "video");
console.log(`${video.width}x${video.height}, ${info.duration.toFixed(1)}s`);

GET /v1/convert/media-info

Same probe, but the media URL is passed as a query parameter instead of a JSON body.

Query parameters

Parameter Type Required Description
url string yes Public URL of the media file to probe

Example — curl

curl -G "https://convert.toolkitapi.io/v1/convert/media-info" \
  -H "X-API-Key: $CONVERT_API_KEY" \
  --data-urlencode "url=https://example.com/clip.mp4"

Use cases

  • Upload validation — Reject files that don't meet resolution or codec requirements.
  • UI enrichment — Show duration and dimensions next to media thumbnails.
  • Transcode preflight — Decide whether a file needs conversion before running FFmpeg.
  • Asset cataloguing — Populate metadata fields when importing media into a DAM.

Errors

Status Meaning
400 URL is not a valid media file, or the probe failed
401 Missing or invalid API key
422 Validation error (missing url)
502 Could not download the source file
503 ffprobe is not available on the server

See Error Handling for the shared error envelope.