Video thumbnail API: extract a cover frame at any timestamp
Point Fotovid at a timestamp and it captures that one frame as a hosted image — ready to drop straight in as a gallery preview, feed thumbnail, or video poster.
curl -X POST https://api.fotovid.co/v1/video/extract-cover \
-H "Authorization: Bearer p6_YOUR_KEY_ID:YOUR_SECRET" \
-H "Content-Type: application/json" \
-d '{
"source_url": "https://cdn.yoursite.com/clip.mp4",
"params": {
"at": 3
}
}'Why grabbing one frame is harder than it looks
A video thumbnail is conceptually trivial: seek to a timestamp, decode one frame, encode it as an image. In practice you either run ffmpeg yourself or lean on a bloated media platform. Bundling an ffmpeg binary blows past serverless size and memory limits, cold-starts get slow, and decoding a large source can exceed a function's timeout. And you rarely need the whole toolchain — you just need one frame out.
- ffmpeg binaries are too large for most serverless bundles and eat cold-start budget
- Decoding a big video to pull a single frame can blow function memory and timeout limits
- You have to fetch the source, run the process, then upload the result somewhere yourself
- Full media platforms bundle transforms, storage, and CDN you don't want just to get one poster
Request parameters
POST /v1/video/extract-cover
| Field | Type | Default | Description |
|---|---|---|---|
| source_url* | string (URL) | — | HTTPS URL of the source video (read via HTTP Range) |
| params.at | number | 1 | Seconds into the video to grab the frame |
Your first call in three steps
- 1Get a free API key
Sign up and create a key. You authenticate every request with an Authorization: Bearer p6_<key_id>:<secret> header. New keys start on free usage credits, so you can wire up thumbnails before you pay anything.
- 2Call POST /v1/video/extract-cover
Send a JSON envelope with source_url pointing at the https URL of your video, plus a params object where you can specify the timestamp to grab (as an HH:MM:SS.mmm string or seconds). Fotovid fetches the source, decodes the frame at that point, and encodes it as an image on our infrastructure — no ffmpeg in your stack.
- 3Use the returned hosted image URL
The response is flat JSON with id, type, and a fotovid-hosted url pointing at the extracted frame, along with an expires_at. Render it directly as a thumbnail or poster, or download it and store your own copy in your bucket so you control its lifetime.
Frequently asked questions
Ship it with one API call
Grab a free key and make your first call in under five minutes.