> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://fastpix.com/docs/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://fastpix.com/docs/_mcp/server. # 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](/getting-started/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](/video-security/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](/video-on-demand-api/upload-and-import-videos/create-media) or [directly from a device](/video-on-demand-api/upload-and-import-videos/direct-upload-video-media). * See the [5-minute quick start](/get-started/quickstart) 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](/webhooks/webhook-event-reference) 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:** ```text 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. | Parameter | Type | Description | | :--------- | :------ | :--------------------------------------------------------------------------------------------------------------------------------- | | `time` | Long | Time (in seconds) within the video timeline from which the image is retrieved. | | `width` | Int | Width of the thumbnail in pixels. Defaults to the original video width. | | `height` | Int | Height of the thumbnail in pixels. Defaults to the original video height. | | `fit_mode` | String | Controls how the frame fits the requested `width` and `height`. Valid values: `preserve`, `stretch`, `crop`, `intellicrop`, `pad`. | | `flip_v` | Boolean | Flips the image vertically after all other transformations. | | `flip_h` | Boolean | Flips the image horizontally after all other transformations. | > **NOTE** > > If no parameters are provided, FastPix returns a frame from the middle of the video. \ **Example:** ```text 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](/video-security/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:** ```text 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 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. 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](/video-on-demand/create-gifs-from-a-video) guide. Thumbnails require the asset to reach `status: ready`. Subscribe to the `video.asset.ready` [webhook](/webhooks/webhook-event-reference) or poll the asset before building the image URL. 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](/video-security/generate-jwts-for-secure-media). 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](/video-on-demand/create-gifs-from-a-video) * [Generate JWTs for secure media](/video-security/generate-jwts-for-secure-media) * [Webhooks collection](/webhooks/webhook-event-reference)