Video Thumbnail
video-thumbnail
Generates a thumbnail from a video. It accepts one of two forms:
- A number representing the time in seconds at which the thumbnail should be generated (e.g.
video-thumbnail=5,video-thumbnail=0.04) - Empty value or
0(default): Iris auto-selects the most representative frame using color-histogram scoring, avoiding black and solid-color frames
When video-thumbnail is specified, Iris returns an image rather than a video. The fm parameter is optional and sets the output image format (e.g. fm=jpg, fm=webp, fm=png).
Additionally, it allows you to use any parameter from the Rendering API to transform and optimize the thumbnail, including (but not limited to) auto=compress,format, w, h, fit, and crop.
Thumbnail and video are separate requests
A URL with video-thumbnail returns an image, not a video. You must use two
separate URLs: one for the video (fm=mp4) and one for the thumbnail
(fm=jpg&video-thumbnail=N). A single URL cannot return both.
Common use cases
First frame
To extract the first frame, use a small positive timestamp such as video-thumbnail=0.04 (approximately one frame at 24 fps). Do not use video-thumbnail=0 — it triggers auto-selection, not frame 0.
Last frame
Timestamps beyond the video’s duration are clamped to the final frame. To reliably target the last frame, first fetch the video duration via fm=json (a separate request), then pass that value as the timestamp — for example, video-thumbnail=22.08 for a 22-second video. Alternatively, a sufficiently large value such as video-thumbnail=99999 will clamp to the last frame for any video.
Using video-thumbnail with HTML
Use the poster attribute on the <video> element for the thumbnail URL and src for the video URL:
<video
controls
poster="https://myhost.imgix.net/myvideo.mp4?fm=jpg&video-thumbnail=3"
src="https://myhost.imgix.net/myvideo.mp4?fm=mp4"
>
Your browser does not support the video tag.
</video>You can use the Video Thumbnail Picker Demo below to test the video-thumbnail parameter.