Create thumbnails from a video

FastPix generates on-demand thumbnails that serve as the video previews, social cards, and poster images driving first-click impressions and SEO for your content. Build the image URL from https://images.fastpix.com/{PLAYBACK_ID}/thumbnail.{jpg|png|webp} and control the frame, dimensions, format, and fit mode through query parameters.

Prerequisites

• A FastPix account with an active workspace (Activate your account)
• A ready on-demand media with a known playbackId.
• For private assets, a signing key to generate a JWT (Generate JWTs for secure media)

Upload a video to FastPix

Before requesting a thumbnail, upload an asset and wait for transcoding to complete.

• Upload the source from a URL or directly from a device.
• See the 5-minute quick start guide for end-to-end setup.

Confirm the video is ready

Thumbnail requests only succeed after FastPix finishes encoding and packaging the asset.

• Poll the media or subscribe to webhooks and wait until status is ready.
• Requesting a thumbnail before the media is ready returns an error or an incomplete image.

Request a thumbnail

Build the image URL from the playbackId of the ready asset. FastPix serves thumbnails from the images.fastpix.com host.

URL format:

https://images.fastpix.com/{PLAYBACK_ID}/thumbnail.{png|jpg|webp}

Supported formats are jpg, png, and webp. Use webp when you need smaller payloads on the web without a visible quality drop. If you omit query parameters, FastPix returns a frame from the middle of the video, a sensible default for a poster image.

Customize the thumbnail with query parameters

Add query parameters to the image URL to pick the frame, resize the output, or change the crop behavior. Combine parameters to match your layout, start with defaults and adjust from there.

NOTE

If no parameters are provided, FastPix returns a frame from the middle of the video.

Example:

https://images.fastpix.com/7e3e2039-7468-4e6d-9197-44718d142d1f/thumbnail.jpg?width=320&height=200&fit_mode=preserve

Access thumbnails for private media

Thumbnail URLs inherit the accessPolicy of the playbackId. An accessPolicy is the public-or-private setting FastPix stores on each playbackId and applies to every asset derived from it, including images.

• Public thumbnail: Thumbnails are accessible directly using the thumbnail URL..
• Private thumbnail: Thumbnails require a valid JWT token to authorize access. .

For full JWT generation steps, see Generate JWTs for secure media.

NOTE

• token is required only when the playbackId is private.
• For a public playbackId, the token parameter is not needed.

Example:

https://images.fastpix.com/36656168-2929-464c-8e7c-9b98461c5f79/thumbnail.jpg?token={JWT}&width=320&height=200&fit_mode=preserve

Choose a fit mode

Each fit_mode value trades off aspect-ratio preservation against filling the requested box. Pick one based on the surface where the thumbnail renders.

preserve (default)

Retains the source aspect ratio and resizes the frame to fit inside the requested width and height. For a 16:9 source requested at 200x200, FastPix returns a 200x112 image. No distortion, no cropping.

stretch

Forces the frame to exactly match width and height, ignoring the source aspect ratio. Fills the box but distorts the image. Both width and height are required.

crop

Resizes the frame to fill width and height, centers on the middle, and crops any excess. Both width and height are required. Use it for uniform grids where subjects are centered in frame.

intellicrop

Runs a focal-point detector on the frame and centers the crop on the detected subject — faces, products, or other salient objects. Both width and height are required. Choose intellicrop when a generic center-crop cuts off the subject.

pad

Keeps the source aspect ratio and adds letterbox bars to fill width and height. Both width and height are required. Use pad when you need a fixed aspect ratio container and cannot crop.

NOTE

Use intellicrop for subject-driven content such as talking-head videos or product shots. Use pad when the full frame must remain visible.

Frequently asked questions

How does FastPix pick a frame when I don’t pass time?

FastPix returns a frame from the middle of the video timeline. Pass time in seconds to select any other frame, and combine it with intellicrop to keep the subject centered.

Can I generate animated or storyboard thumbnails?

The thumbnail endpoint returns a single still image in jpg, png, or webp. For animated previews and storyboard sprites used in scrubbing UIs, see the animated GIFs and previews guide.

Why does my thumbnail return an error immediately after upload?

Thumbnails require the asset to reach status: ready. Subscribe to the video.asset.ready webhook or poll the asset before building the image URL.

Do I need a separate token for thumbnails on a private playbackId?

No, FastPix accepts the same signed JWT format used for playback. Pass it in the token query parameter on the image URL. See Generate JWTs for secure media.

Which format should I use for web poster images?

Use webp for modern browsers to reduce payload size while preserving quality. Fall back to jpg where webp is not supported. png is best when you need alpha or sharp text overlays.

What’s next?

• Get animated GIFs and previews
• Generate JWTs for secure media
• Webhooks collection