Seek to the timestamp you want on the input, then ask for exactly one frame with -frames:v 1. ffmpeg picks the image encoder from the output filename, so a .jpg name is all it takes.
The ffmpeg command
What you would run locally, for reference.
ffmpeg -ss 00:00:05 -i input.mp4 -frames:v 1 -q:v 2 thumbnail.jpg
The API request
The same flags, sent as JSON. Authenticate with
Authorization: Token <your-api-token>.
{
"global_options": [
"-y"
],
"inputs": [
{
"input_source": "https://example.com/input.mp4",
"options": [
"-ss",
"00:00:05"
]
}
],
"outputs": [
{
"filename": "thumbnail.jpg",
"options": [
"-frames:v",
"1",
"-q:v",
"2"
]
}
]
}
Worth knowing
- Seeking on the input (before
-i) jumps straight to the keyframe instead of decoding from the start, which is what keeps this job down to a second or two. - A timestamp past the end of the video produces no frame and the job fails. Check the duration first with ffprobe if you don't control the source.
What it costs
Jobs bill in processing seconds — the CPU time this one actually uses — with a floor of 25 seconds per GB pulled out of storage to run it, so a stream-copy still counts. Uploading the output and downloading it afterwards are free. See the plans.