Seek with -ss before -i for one frame: a thumbnail at 4 seconds takes under a second. thumbnail=300 lets ffmpeg pick the most typical of 300 frames; on ReelSDK's API that pick cost under a fifth of a cent, at $0.02 per compute minute.

Video thumbnails with ffmpeg

Pick the frame by time, by looks, by keyframe or by cut; on a 10-second 1080p clip each takes 1 to 3 seconds. ReelSDK's API refuses the -skip_frame keyframe shortcut, and scene detection at the usual 0.3 can write nothing at all.

GuidesUpdated

frame at 4 s
ffmpeg -ss 4 -i in.mp4 -frames:v 1 -update 1 -q:v 2 thumb.jpg

-ss before -i jumps close to 4 s and decodes the few frames up to it, so the result is exact and fast. -update 1 writes a single file; without it ffmpeg 8.1 warns that the name has no image sequence pattern.

Variations

The other commands you will need

  1. Let ffmpeg pick a good frame

    The thumbnail filter looks at a batch of frames and keeps the most typical one, which skips black frames and flashes. With a batch of 300 it read the whole clip and chose a frame near the end.

    best frame
    ffmpeg -i in.mp4 -vf thumbnail=300,scale=1280:-2 -frames:v 1 -update 1 -q:v 2 best.jpg
  2. Every keyframe

    Keyframes are the frames the encoder stored whole, so they make clean stills. select keeps them and -fps_mode vfr stops ffmpeg from padding the gaps with copies. Our clip has 2.

    keyframes
    ffmpeg -i in.mp4 -vf "select='eq(pict_type,I)'" -fps_mode vfr -q:v 2 -frames:v 20 key_%02d.jpg
  3. A frame at each scene change

    Print the scene scores first, then pick the threshold. The usual 0.3 found nothing on our clip, whose cuts are soft crossfades; 0.02 gave 5 frames.

    scene changes
    ffmpeg -i in.mp4 -vf "select='gte(scene,0)',metadata=print:key=lavfi.scene_score" -an -f null -
    ffmpeg -i in.mp4 -vf "select='gt(scene,0.02)',scale=640:-2" -fps_mode vfr -q:v 3 -frames:v 20 scene_%02d.jpg

The flags

The options in these commands

The options in these commands
FlagWhat it doesUsed here
-ss 4Before -i: seeks the input, then decodes up to the exact timeFrame at 4 s
-frames:v 1Stops after one video frameFrame at 4 s, best frame
-update 1Treats the name as one file, not a numbered patternFrame at 4 s, best frame
thumbnail=300Keeps the most typical frame of each batch; the default batch is 100Best frame
eq(pict_type,I)A select test that keeps keyframes onlyKeyframes
gt(scene,0.02)Keeps frames whose scene score, 0 to 1, is above 0.02Scene changes
-fps_mode vfrWrites only the selected frames, without duplicatesKeyframes, scene changes
-q:v 2JPEG quality; lower is betterAll four

Sources: ffmpeg filters: thumbnail, select, ffmpeg documentation: -ss, checked November 2026.

How the thumbnail filter chooses

In FFmpeg 8.1's source, thumbnail builds a colour histogram for each frame in the batch, averages them, and keeps the frame closest to that average. Black frames and flashes sit far from the average, so they rarely win.

It holds the whole batch in memory; the manual warns that "a bigger n value will result in a higher memory usage". Our run with 300 full HD frames peaked at almost 1 GB. Scale down before it, or use a smaller batch, on long clips.

When scene detection finds nothing

gt(scene,0.3) is the threshold most examples use, and on hard cuts it works. Our clip changes shots with crossfades, so no single frame differs much from the last: after the first frame, no score reached 0.03. ffmpeg selected nothing and exited with code 234, "Nothing was written into output file".

The fix is to look before you choose. The first scene command prints a score for every frame; from those, 0.02 picked 5 frames.

Running it on the API

Locally, -skip_frame nokey before -i makes the decoder skip everything but keyframes, which made that job about five times faster. The API refuses it with a 400: "-skip_frame is not supported". Use the select command above instead; it returns the same frames.

Image sequences on the API stop at 20 frames, so each numbered command carries -frames:v 20, and every file goes in outputs by its real name. Jobs are billed per compute second; see pricing.

Without installing ffmpeg

The same command as one API call

Send the args of the best-frame command to POST /v1/ffmpeg. Each job runs ffmpeg 8.1 on a fresh machine at $0.02 per compute minute, billed per second; this one finished in about 4 seconds, cost under a fifth of a cent, and picked the same frame as our local run. A second job ran the keyframe command.

terminalTry it
curl "https://api.reelsdk.com/v1/ffmpeg?wait=60" \
  -H "Authorization: Bearer $REELSDK_KEY" \
  --json '{
    "inputs": {
      "in.mp4": "https://api.reelsdk.com/f/lib/demo/landscape.mp4"
    },
    "args": [
      "-i", "in.mp4", "-vf", "thumbnail=300,scale=1280:-2", "-frames:v", "1",
      "-update", "1", "-q:v", "2", "best.jpg"
    ],
    "outputs": ["best.jpg"]
  }'
ReelSDK video API: The frame the thumbnail filter picked: Seville at dusk
best.jpg from the API: 1280x720, a frame near the end of the clip.Input: 1920x1080 inputkey_01.jpgkey_02.jpg

FAQ

Questions, answered

How do I get a thumbnail from a video with ffmpeg?

Run ffmpeg -ss 4 -i in.mp4 -frames:v 1 -update 1 -q:v 2 thumb.jpg to write the frame at 4 seconds as a JPEG. On a 1080p clip it takes under a second.

How do I let ffmpeg choose the best thumbnail?

Use -vf thumbnail=300 with -frames:v 1. It keeps the most typical frame from each batch of 300; the default batch is 100.

Why does my scene detection command write no images?

The threshold is too high for your cuts. Soft crossfades scored below 0.03 on our clip, so 0.3 found nothing. Print the scores with metadata=print:key=lavfi.scene_score and pick a threshold from them.

How do I extract only keyframes?

Use -vf "select='eq(pict_type,I)'" -fps_mode vfr. -skip_frame nokey is faster locally, but the API refuses it.

Ready to build?

Ship video from your app today

Your first $0.50 is free, and one key covers every endpoint.

Moonlit lake with a lit cabin under the mountains