Grab a video thumbnail
A video without a poster frame is a gray box waiting to be clicked on faith. This endpoint pulls one still image from any timestamp you name, so the thumbnail actually represents the moment worth clicking for.
Run it online
Run this on our servers with your account. Free tools run in your browser; this one bills your KIT balance per the price above.
The gray box problem
Browsers and players default to showing nothing, a black rectangle, or an auto-picked frame that's usually a mid-transition blur, unless something explicitly supplies a poster image. That default costs clicks, because people decide whether to watch in the half-second before they hit play, and a bad frame reads as a broken upload even when the video itself is fine. video.thumbnail solves the narrow, specific problem of getting one representative frame out of a video file on demand.
How the extraction works
POST /video/thumbnail with the source video and the timestamp you want captured, and the response comes back immediately as a task_id while the frame extraction runs in the background. The still image arrives through a signed webhook call once it's ready, or waits at a signed link valid for 24 hours if that fits your retrieval flow better.
Why the timestamp matters more than people expect
Video decoding works around keyframes — full images stored periodically through the file, with the frames in between reconstructed from the differences against them. Landing exactly on the requested second sometimes means decoding forward from the nearest keyframe rather than just seeking to it, which is why a thumbnail extractor has to actually decode video, not just read a file header. Poster frames have been part of video delivery since the earliest web video players needed something to show before playback started, and the underlying mechanics haven't really changed.
Where thumbnails fit into a bigger system
A content management system that ingests videos in bulk typically needs a thumbnail the moment a video lands, well before anyone manually reviews the footage — a catalog page, an admin dashboard, and a search results grid all need something to show immediately. Because the task is priced per request and billed once per video regardless of how it's later displayed, generating thumbnails as part of the initial ingestion step, rather than on-demand per page view, keeps a media library predictable to run at scale, even as the number of videos in it climbs into the thousands.
What you can do with it
Catalog poster images
A video library generates a thumbnail for every uploaded file at ingestion time, so browse and search pages never show an empty placeholder.
Chapter markers for long recordings
An e-learning platform pulls a thumbnail at the start of each lesson segment to build a visual chapter selector for students.
Social share preview
A publishing platform captures a frame a few seconds into a clip, past the usual black intro, to use as the link preview image on social platforms.
Moderation review grid
A user-generated content platform grabs a mid-video frame for every upload to populate a moderation queue reviewers can scan visually.
FAQ
How do I get a thumbnail from a video with the API?
POST the source video and the timestamp you want to /video/thumbnail, keep the returned task_id, and retrieve the still image by webhook or a signed link valid for 24 hours.
Is the video thumbnail API free?
No, there is no free tier or trial; it costs $0.077 per request plus $0.0045 per video, and a failed extraction is never charged.
Can I pick any timestamp for the thumbnail?
Yes, you specify the exact second you want captured, rather than relying on an auto-picked or default frame.
What format is the thumbnail delivered in?
The endpoint returns a standard still image extracted from the requested frame, ready to use directly as a poster or preview.
Can I generate thumbnails for many videos at once?
Yes, submit one async task per video and collect each thumbnail by webhook as it completes, which fits bulk ingestion pipelines naturally.
Is this endpoint live yet?
It's in deployment now, so check the endpoint status before sending production traffic since it isn't accepting jobs at this moment.
Does video length affect the price?
No, thumbnail extraction is priced per request plus a flat per-video fee, not by the video's duration.
Is my video stored after the thumbnail is generated?
No, the source video and extracted image are deleted after the retention window and are never used for training.
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
Prefer to automate it? One authenticated POST creates the task; the result comes back by webhook or a signed link. The same capability also runs here on the web, and soon from our app, email and Telegram.
Call it from your stack
curl -X POST https://api.kit.forhosting.com/video/thumbnail \
-H "Authorization: Bearer $KIT_KEY" \
-H "Content-Type: application/json" \
-d '{"input":"…"}'const res = await fetch("https://api.kit.forhosting.com/video/thumbnail", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.KIT_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"input": "…"
})
});
const { task_id } = await res.json();import os, requests
res = requests.post(
"https://api.kit.forhosting.com/video/thumbnail",
headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
json={
"input": "…"
},
)
task_id = res.json()["task_id"]<?php
$res = file_get_contents("https://api.kit.forhosting.com/video/thumbnail", false, stream_context_create([
"http" => [
"method" => "POST",
"header" => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
"content" => '{"input":"…"}',
],
]));
$task = json_decode($res, true);body := bytes.NewBufferString(`{"input":"…"}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/video/thumbnail", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)Example request
{
"input": "…"
}Example response
{
"task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
"type": "video.thumbnail",
"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. |