Extract Frames and Thumbnails

A thumbnail is just a single frame

A thumbnail or preview image is one still frame pulled out of a video at a specific moment. You pick a timestamp, tell the API to emit exactly one frame, and choose an image outputFormat. The job runs the same way every transcode does. The only difference is that the output is an image instead of a video.

You already have createTranscode, waitForJob, and getDownloadUrl from Lesson 3. This lesson just changes the request body you pass to createTranscode.

The request body

To grab a single JPEG frame at the two-second mark, send an image outputFormat and three options:

{
  inputs: [{ url }],
  outputFormat: 'jpeg',
  options: [
    { option: '-ss', argument: '00:00:02' },
    { option: '-frames:v', argument: '1' },
    { option: '-q:v', argument: '2' },
  ],
}

• outputFormat accepts jpeg, png, gif, and webp for stills. Use 'jpeg', not 'jpg'.
• -ss seeks to the timestamp. It accepts 'HH:MM:SS' or plain seconds like '2'.
• -frames:v sets how many frames to output. Use '1' for a single still.
• -q:v sets image quality, where lower is higher quality. '2' is high quality for JPEG.

An extractFrame helper

Wrap the body in a small helper so you can pass a timestamp and an optional format. It calls the same createTranscode you built in Lesson 3.

// extract-frame.mjs
async function extractFrame(url, timestamp = '00:00:02', { format = 'jpeg' } = {}) {
  return createTranscode({
    inputs: [{ url }],
    outputFormat: format,
    options: [
      { option: '-ss', argument: timestamp },
      { option: '-frames:v', argument: '1' },
      { option: '-q:v', argument: '2' },
    ],
  })
}

A PNG variant

JPEG is small and fine for photographic frames. When you need a lossless image, say a frame with sharp text or UI, pass png instead. The -q:v option is a JPEG quality control, so it simply has no effect here, but leaving it in is harmless.

// Same helper, PNG output:
const job = await extractFrame(videoUrl, '00:00:05', { format: 'png' })

// Or spell out the body directly:
await createTranscode({
  inputs: [{ url: videoUrl }],
  outputFormat: 'png',
  options: [
    { option: '-ss', argument: '00:00:05' },
    { option: '-frames:v', argument: '1' },
  ],
})

Putting it together with the Lesson 3 flow

Extracting a frame is the full create, poll, and download lifecycle you already know. Submit the job with extractFrame, wait for it with waitForJob, get a signed URL with getDownloadUrl, then stream the bytes to disk.

// thumbnail.mjs
import { writeFile } from 'node:fs/promises'

const videoUrl = 'https://example.com/input.mp4'

// 1. Submit the frame-extraction job
const { id } = await extractFrame(videoUrl, '00:00:02', { format: 'jpeg' })

// 2. Poll until it finishes
await waitForJob(id)

// 3. Get a signed URL for the output image
const downloadUrl = await getDownloadUrl(id)

// 4. Download the image to disk
const res = await fetch(downloadUrl)
if (!res.ok) {
  throw new Error(`Download failed: ${res.status}`)
}
const bytes = Buffer.from(await res.arrayBuffer())
await writeFile('thumbnail.jpeg', bytes)

console.log('Saved thumbnail.jpeg')

Run it:

node --env-file=.env thumbnail.mjs
# Saved thumbnail.jpeg

Next up: go beyond presets with custom FFmpeg options and filters to resize, crop, and overlay.