DEV Community

Javid Jamae
Javid Jamae

Posted on • Originally published at ffmpeg-micro.com

How to Generate Video Thumbnails with FFmpeg (CLI + API)

#ffmpeg #video #api #tutorial

Originally published at ffmpeg-micro.com

You need a thumbnail from a video file. Maybe you're building a video gallery, generating preview images for a CMS, or creating social media cards from uploaded content. The usual advice is to install FFmpeg on your server and write extraction scripts. That works until you need it in production.

How FFmpeg Thumbnail Extraction Works

FFmpeg can extract a single frame from any video using two flags: -ss to seek to a timestamp and -frames:v 1 to grab exactly one frame.

ffmpeg -ss 5 -i input.mp4 -frames:v 1 thumbnail.jpg
Enter fullscreen mode Exit fullscreen mode

This grabs the frame at the 5-second mark and saves it as JPEG. The output format is determined by the file extension. Use .png for PNG, .webp for WebP.

One detail that trips people up: the position of -ss matters. Placing it before -i uses input seeking, which is fast but jumps to the nearest keyframe. Placing it after -i decodes everything up to that point, which is slower but frame-accurate. For thumbnails, input seeking is almost always fine.

Extract a PNG Thumbnail at a Specific Timestamp 

ffmpeg -ss 00:01:30 -i input.mp4 -frames:v 1 thumbnail.png
Enter fullscreen mode Exit fullscreen mode

PNG gives you lossless quality. That matters when the thumbnail feeds into another image processing pipeline. The tradeoff is file size: a PNG thumbnail runs 5-10x larger than the equivalent JPEG.

Extract Thumbnails at Regular Intervals

Need a thumbnail strip or chapter preview images? Use the fps filter:

ffmpeg -i input.mp4 -vf "fps=1/10" -q:v 2 thumb_%03d.jpg
Enter fullscreen mode Exit fullscreen mode

This outputs one frame every 10 seconds. Files are numbered thumb_001.jpg, thumb_002.jpg, and so on. The -q:v 2 flag sets JPEG quality (lower number means better quality, range is 2-31).

Generate Video Thumbnails with an API

Running FFmpeg on a server means managing the binary, handling disk space for temp files, and scaling infrastructure when traffic spikes. FFmpeg Micro is a cloud API that lets you extract thumbnails with a single HTTP call. No FFmpeg installation, no server to manage.

curl -X POST https://api.ffmpeg-micro.com/v1/transcodes \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "inputs": [{"url": "https://example.com/video.mp4"}],
    "outputFormat": "jpeg",
    "options": [
      {"option": "-ss", "argument": "5"},
      {"option": "-frames:v", "argument": "1"}
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

The response returns a job ID. Poll for completion, then download:

curl https://api.ffmpeg-micro.com/v1/transcodes/JOB_ID \\
  -H "Authorization: Bearer YOUR_API_KEY"
Enter fullscreen mode Exit fullscreen mode 
curl https://api.ffmpeg-micro.com/v1/transcodes/JOB_ID/download \\
  -H "Authorization: Bearer YOUR_API_KEY"
Enter fullscreen mode Exit fullscreen mode

FFmpeg Micro supports JPEG, PNG, GIF, and WebP as output formats for thumbnail extraction. Change "outputFormat": "jpeg" to "png" or "webp" depending on your needs.

Upload a Video First, Then Extract

If your video isn't hosted at a public URL, use the three-step upload flow:

  1. Request a presigned upload URL via POST /v1/upload/presigned-url
  2. Upload the file directly to the returned cloud storage URL
  3. Confirm the upload via POST /v1/upload/confirm to get your permanent fileUrl

Use that fileUrl as the input in your transcode request.

Common Pitfalls with FFmpeg Thumbnail Extraction

Black frames at timestamp 0. Seeking to the very start of a video often lands on a black frame, especially with fade-in intros. Start at 1-5 seconds instead.

Timestamp past the video length. If you pass -ss 120 on a 60-second video, FFmpeg exits silently with no output. No error, no warning. Always check video duration with ffprobe before extracting.

Washed-out colors. Some codecs produce frames in pixel formats that JPEG can't encode properly. If thumbnails look faded, add -pix_fmt yuvj420p:

ffmpeg -ss 5 -i input.mp4 -frames:v 1 -pix_fmt yuvj420p thumbnail.jpg
Enter fullscreen mode Exit fullscreen mode

iPhone MOV files. iPhone videos use HEVC (H.265). Older FFmpeg builds don't include HEVC decoding. Make sure your build was compiled with --enable-libx265, or use an API like FFmpeg Micro that includes full codec support out of the box.

CLI vs API: Which Should You Use?

Scenario Best approach
One-off local extraction FFmpeg CLI
Batch processing on your machine FFmpeg CLI with a shell script
User uploads in a web app FFmpeg Micro API
Serverless functions FFmpeg Micro API
CI/CD pipeline previews Either works

Use the CLI for local work. Use the API when your app needs thumbnails at runtime from user-uploaded video. No binary to install, no temp files to clean up, no servers to scale.

Frequently Asked Questions

Can I extract a thumbnail from a video URL without downloading it first?

Yes. Both FFmpeg CLI (with -i https://...) and FFmpeg Micro accept HTTP/HTTPS URLs as input. If the video is publicly accessible, you don't need to download or upload anything.

What image format should I use for video thumbnails?

JPEG for web display. Smallest file size, good enough quality for previews and galleries. PNG when you need lossless frames for downstream image processing. WebP if you want better compression than JPEG with similar visual quality.

How do I pick the right timestamp for a thumbnail?

Skip the first few seconds to avoid black frames, title cards, or logo intros. For most content, seeking to 10-25% of the video duration gives a representative frame. For automated systems, extract 3-5 frames at even intervals and pick the one with the highest visual variety.

Does FFmpeg Micro support extracting multiple thumbnails from one video?

Each API call extracts one frame. The requests complete in a few seconds, so fire multiple calls in parallel to build a thumbnail strip or preview timeline quickly.

Top comments (0)