Read a video's metadata
Send a link to a video and get back its duration, container, video and audio codecs, resolution, frame rate and the bitrate of each stream, probed from the streams themselves rather than the file name. Pay per use, no subscription.
This task is not available right now, so it cannot be purchased. Nothing is charged for it.
How it works & APIBefore you transcode, route, bill, or reject a video file, you need to know what it actually is: how long it runs, what codec it's wrapped in, at what resolution and bitrate.
Why a file's real details matter
Before you transcode, route, bill or reject a video, you need to know what it actually is. An upload can claim to be anything: the wrong container, a resolution that does not match its name, a variable bitrate that only shows up halfway through, or an audio track in a codec your player cannot handle. Containers such as MP4 or MKV can wrap streams in dozens of codecs, each storing duration and bitrate its own way, and some tools write inconsistent or missing header details.
How the reading works and where it fits
The service probes the container and every stream instead of trusting the header blindly, then returns duration, formats, codecs, resolution, frame rate, the bitrate of each stream and the stream count in a predictable layout. Because the result is consistent, it sits well in front of other steps: an upload gate that rejects files below a minimum quality, a decision on whether a file needs re-encoding, a storage audit based on real bitrate and duration, or a check against the formats a device supports before playback.
The problem of not knowing what you received
A video upload can claim to be anything: the wrong container, a resolution that doesn't match the filename, a variable bitrate that only shows up mid-file, an audio track encoded in a codec your player doesn't support. The video metadata api exists for the systems that have to make a decision the moment a file lands, whether that decision is 'transcode this' or 'reject this' or 'route this to the right queue,' without a person ever opening the file to look.
What you can do with it
Upload validation gate
A platform checks resolution and duration on every upload before accepting it, rejecting files that don't meet minimum quality standards without downloading the whole thing first.
Smart transcoding routing
A media pipeline reads codec and bitrate to decide whether a file needs re-encoding or can be served as-is, saving unnecessary transcode jobs.
Storage and billing audits
A hosting service periodically pulls metadata across its library to calculate accurate storage costs based on real bitrate and duration rather than file size estimates.
Compatibility checks before playback
An app verifies a video's codec against the target device's supported formats before attempting playback, avoiding a failed stream on the user's end.
FAQ
Is metadata extraction free to try?
There's no free tier — free tiers get abused and slow everyone down. No subscription, no tokens, no invented credits, and a failed task is never charged.
Does it work with any video format?
It reads the common containers and codecs used in production video, such as MP4, MOV, MKV, WebM and their standard audio/video codec combinations.
Do I get charged if the file can't be read?
No, a failed task is retried up to three times and never billed if it ultimately fails; you get a clear error instead.
What details does the report include?
Duration, container format, video and audio codecs, resolution, frame rate, the bitrate of each stream and the number of streams, all returned in a clean, predictable layout instead of a text dump to pick apart.
Why not just trust the file name or header?
Uploads can claim to be anything: the wrong container, a resolution that does not match the name, a bitrate that changes mid-file. Probing the streams themselves catches what an inconsistent or missing header would hide.
Related tools
For developers — API access
Everything on this page is available programmatically. This section is for teams who want to wire it into their own systems; everyone else can just use the tool above.
API endpoint
One authenticated POST creates the task; the result comes back by webhook or a signed link. This capability is currently available through the API, not as an interactive Web tool.
Call it from your stack
curl -X POST https://api.kit.forhosting.com/video/metadata \
-H "Authorization: Bearer $KIT_KEY" \
-H "Content-Type: application/json" \
-d '{"video":"https://example.com/clip.mp4"}'const res = await fetch("https://api.kit.forhosting.com/video/metadata", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.KIT_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"video": "https://example.com/clip.mp4"
})
});
const { task_id } = await res.json();import os, requests
res = requests.post(
"https://api.kit.forhosting.com/video/metadata",
headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
json={
"video": "https://example.com/clip.mp4"
},
)
task_id = res.json()["task_id"]<?php
$res = file_get_contents("https://api.kit.forhosting.com/video/metadata", false, stream_context_create([
"http" => [
"method" => "POST",
"header" => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
"content" => '{"video":"https://example.com/clip.mp4"}',
],
]));
$task = json_decode($res, true);body := bytes.NewBufferString(`{"video":"https://example.com/clip.mp4"}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/video/metadata", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)Example request
{
"video": "https://example.com/clip.mp4"
}Example response
{
"task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
"type": "video.metadata",
"status": "queued",
"_links": {
"result": "/tasks/tsk_…/result"
}
}The API is asynchronous: the call returns a task_id immediately and the result arrives by webhook. Polling is capped at 1 req/s per task.
Pricing
Published price — no tokens, no invented credits. A failed task is never charged.
Limits
max_mb | 500 |
max_minutes | 60 |
max_megapixels | 3.9 |
Errors
| HTTP | Code | Meaning |
|---|---|---|
401 | unauthorized | Missing or invalid API key. |
402 | insufficient_balance | Your balance doesn't cover the task price. |
404 | unknown_type | That task type doesn't exist. |
429 | rate_limited | Too many requests. Use the webhook instead of polling. |
Technical notes
This endpoint reads the container and streams and hands that back as structured data, so no script of yours has to guess.
What a call returns
POST /video/metadata takes a link to the file and, once processed, hands back duration, container format, video codec and audio codec, resolution, frame rate, bitrate for each stream, and basic stream count, all as clean structured JSON, no scraping of a text dump or parsing a command-line tool's console output required.
How the request flow works
Like every task on the platform, this one is asynchronous: you get a task_id the moment you submit, the file is inspected in the background, and the result reaches you as a signed webhook call the moment it's ready, or as a signed link you fetch yourself, valid for 24 hours before it expires along with the source copy.
A little context on why metadata is messy
Video containers such as MP4 or MKV are wrappers that can hold streams encoded in dozens of different codecs, each with its own way of storing duration and bitrate, and some files are muxed by tools that write inconsistent or missing header fields; a proper metadata read has to actually probe the streams rather than trust the container header blindly, which is exactly the work this endpoint does for you.
Where it belongs in automation
Because the result is structured and predictable, it's built to sit in front of other steps: a transcoding pipeline that only converts files above a certain bitrate, an upload gate that rejects anything longer than a set duration, or a catalog system that needs accurate resolution and codec fields for every asset without a human ever opening the file.
Technical questions
How do I get a video's metadata through the API?
Send a POST request to /video/metadata with a link to the file; you receive a task_id right away and the structured metadata later via webhook or signed link.
What fields does the video metadata api return?
Duration, container format, video and audio codecs, resolution, frame rate, bitrate and stream count, delivered as structured JSON.
How much does a metadata request cost?
It's $0.077 per request plus $0.0045 per video, published openly with no invented credit units.
Can I use this to bulk-audit a large video library?
Yes, since each request is billed individually and processed asynchronously, it scales naturally to scripted batch runs across a whole catalog.
Is the endpoint available now?
It's in final deployment and not yet live for jobs, with availability expected very soon under the pricing and endpoint described here.