Update a preview file

Update the default preview file for a video.


You can now use the Platform Management API v2 to manage a media poster.

A thumbnailthumbnail - Preview content that appears in search results or playlists and a posterposter - Preview content that appears in the player before a viewer or a piece of code initiates media playback show a preview of the media content in your player. These previews can increase a viewer's engagement with your media.

For a consistent user experience, a thumbnail and poster for a video are generated from the same preview file. The preview file for a video can be managed by the /videos/thumbnails route.

Each time you upload a video to your JW Player account, the following preview files are created for a thumbnail and poster:

  • A static preview file created from the 10th second of your video
  • A video preview file created from the first 5 seconds of your video

After uploading a video, you can use one of the following approaches to change the default preview images:

Each option is explained in the following sections.



You can also update a video thumbnail within your JW Player dashboard.

Upload a custom preview file


A custom static preview file should adhere to the following standards.

Accepted file formats• .jpg                                                                                                                                      
• .png
Image dimensions1920x1080

A custom video preview file should adhere to the following requirements.

Accepted file formats• .mp4
• .avi
• .3gp
• .wmv
• .flv
• .mov
File duration5-6 seconds (ideal)

If the video file is >10 seconds, only the first 10 seconds will be used for the thumbnail.

If the video file has audio, the audio will not be included in the thumbnail.


Use the following steps to upload a custom preview file:

  1. Add one of JW Player's client libraries to your codebase and import the jwplatform library.
  2. Make an API GET request to /videos/list to return a list of your videos. From the response, locate the video.key of the video whose thumbnail and poster you want to update.
  3. Make an API GET request to /videos/thumbnails/update?video_key={video_key}. A successful request returns a response that contains a link object.
  4. From the response, construct the upload URL by concatenating all properties of the link object.



Although the API response returns "link.protocol": "http", you can use either the HTTP or HTTPS protocol for the upload URL.

  "status": "ok",
  "media": {
    "type": "video",
    "key": "{video_key}"
  "link": {
    "path": "/v1/videos/upload",
    "query": {
      "token": "{query_token}",
      "key": "{video_key}"
    "protocol": "http",
    "address": "upload.jwplatform.com"
  "rate_limit": {
    "reset": 1573744740,
    "limit": 60,
    "remaining": 59
link.protocol + "://" + link.address + link.path + "?api_format=json" + "&key=" + link.query.key + "&token=" + link.query.token

  1. Make an API POST request to the upload URL that includes the location of your static or video thumbnail.
curl POST "{upload_url}" \
-F "[email protected]_PATH"
'use strict';

const JWPlatformAPI = require('jwplatform');
const resolve = require('path').resolve;
const axios = require('axios');
const FormData = require('form-data');
const concat = require("concat-stream");
const fs = require('fs');

// TODO: Enter API V1 credentials
const jwApiInstance = new JWPlatformAPI({
    apiKey: '',
    apiSecret: '',

// TODO: Enter file path and video key (media ID)
const filePath = '';
const videoKey = '';

    .update({ video_key: videoKey })
    .then(response => {
        const { path, protocol, address, query } = response.link;
        const uploadUrl = `https://${address}${path}?api_format=json&key=${query.key}&token=${query.token}`;
        const formData = new FormData();
        formData.append("file", fs.createReadStream(resolve(filePath)));
            concat({encoding:'buffer'}, (data) => {
                axios.post(uploadUrl, data, {
                    headers: formData.getHeaders()
                }).then(response => console.log(response))

Choose a video frame for the static preview file



You cannot use this approach to create a custom video preview file.

  1. Make a /videos/list call to return a list of your videos. From the response, locate the video.key of the video whose thumbnail and poster you want to update.
  2. Identify the timestamp of a frame from the video.
  3. Convert the timestamp value into seconds.
  4. Make a GET call to /videos/thumbnails/update?position={timestamp_in_seconds}.

Did this page help you?