Manage a media poster

Replace a default poster with a custom poster for a media.

A poster shows a preview of the media content in your player. Since a poster can increase a viewer's engagement with your media, two types of posters are created each time you upload a video to your JW Player account:

An image (static) poster created from the 10th second of your video
A video (motion) poster created from the first 5 seconds of your video

Sometimes a poster may not be the most engaging moment of your video. The thumbnails resource allows you to manage your media posters:

Upload a custom poster
Select a poster from the video
Replace the current poster with a previous poster
List and review all posters associated with a media
Delete a poster

For a media resource, you can only select one static poster and one motion poster to be shown to your viewers. Previous posters remain associated to the media resource as thumbnails. An associated thumbnail can always be promoted to a poster to replace the current poster.

🔑
You can also update a video as a thumbnail (poster) from your JW Player dashboard.

Upload and promote a custom static or video poster

Standards

A custom static poster should adhere to the following standards.

Item	Details
Accepted File Formats	.gif .jpeg .png .webp
Image Dimensions	1920x1080

A custom video poster should adhere to the following standards.

Item	Details
Accepted File Formats	.mp4 .avi .3gp .wmv .flv .mov
File Duration	5-6 seconds (ideal) If the video file is >10 seconds, only the first 10 seconds will be used for the thumbnail.
Audio	N/A If the video file has audio, the audio will not be included in the thumbnail.

Implementation

In order to update a media's poster image, a new custom thumbnail must be created and promote to replace the current poster.

Make a POST /v2/sites/{site_id}/thumbnails to create a thumbnail resource to contain the poster image and associate it which a specific media resource. Before being promoted, all potential poster images are stored as thumbnails.

Within the JSON object, you must specify the upload.method, upload.thumbnail_type, and relationships.media.id. Refer to the POST /v2/sites/{site_id}/thumbnails reference for more information about these required and additional optional body parameters.

The API call returns a response with the upload_link location.

curl -X POST "https://api.jwplayer.com/v2/sites/{site_id}/thumbnails" \
    -H 'Authorization: Bearer {v2_api_secret}' \
    -H 'Content-Type: application/json' \
    -d '{
            "upload": {
                "method": "direct", 
                "thumbnail_type": "{static|video}"
            },
            "relationships": {
                "media": [{"id": "{media_id}"}]
            }
        }'

{
  "created": "2021-09-02T19:54:15+00:00",
  "delivery_url": null,
  "file_type": "jpeg",
  "id": "1234abcd",
  "last_modified": "2021-09-02T19:54:15+00:00",
  "metadata": {},
  "relationships": {
    "media": [
      {
        "id": "{media_id}",
        "is_poster": false
      }
    ]
  },
  "schema": null,
  "source_type": "custom_upload",
  "status": "created",
  "thumbnail_type": "static",
  "type": "thumbnail",
  "upload_link": "https://jwplayer-upload-dev.s3-accelerate.amazonaws.com/?AWSAccessKeyId=&Signature=&Expires=1630616055"
 }

Upload the custom poster file to the upload_link location. The custom poster must be of the thumbnail_type specified in the previous step: an image for "thumbnail_type": "static" or a video for "thumbnail_type: video".
```
curl -X PUT --upload-file ~/path/to/your/image.jpg "{upload_link}"
```
```
curl -X PUT --upload-file ~/path/to/your/image.jpg "{upload_link}" -H 'Content-Type: {mime_type}'
```

After the uploading process has completed, make a GET /v2/sites/{site_id}/thumbnails/{thumbnail_id} call to retrieve the thumbnail transcoding status. When "status": "ready" is returned by the API call, continue to the next step.
```
curl -X GET "https://api.jwplayer.com/v2/sites/{site_id}/thumbnails/{thumbnail_id}" \
    -H 'Authorization: Bearer {v2_api_secret}' \
    -H 'Content-Type: application/json'
```

Make a PATCH /v2/sites/{site_id}/thumbnails/{thumbnail_id} call to promote the thumbnail to replace the current poster. In the JSON body, add "relationships.media[].is_poster": "true".
```
curl -X PATCH "https://api.jwplayer.com/v2/sites/{site_id}/thumbnails/{thumbnail_id}" \
    -H 'Authorization: Bearer {v2_api_secret}' \
    -H 'Content-Type: application/json' \
    -d '{
            "relationships": {
                "media": [{"id": "{media_id}", "is_poster": true}]
            }
        }'
```
📘
A media can have only one static poster and one motion poster. Promoting a thumbnail to poster will demote the current poster for the media with the same thumbnail_type.

The poster for the media has been updated. To verify that the new poster is available, copy and paste in the following link into a browser window: https://cdn.jwplayer.com/v2/media/{media_id}/poster.jpg. Be sure to replace {media_id} with the ID of the media.

Create and promote a thumbnail from a media

Thumbnails can be created from a media by specifying either the index in the video's thumbnail strip (thumbstrip_index) or a video position (video_position).

Make a POST /v2/sites/{site_id}/thumbnails to create a thumbnail resource to contain the poster image. Before being promoted, all potential poster images are stored as thumbnails.

Within the JSON object, you must specify the upload.source_type, upload.source_media_id, and upload.video_position or upload.thumbstrip_index. Refer to the POST /v2/sites/{site_id}/thumbnails reference for more information about these required and additional optional body parameters.

The API call returns a response with the id for the thumbnail resource.

💡
When defining upload.thumbstrip_index, use the following URL to preview the available thumbnails in the thumbnail strip: https://cdn.jwplayer.com/strips/{media_id}-120.jpg. Be sure to replace {media_id} with ID of the media.
```
curl -X POST "https://api.jwplayer.com/v2/sites/{site_id}/thumbnails" \
    -H 'Authorization: Bearer {v2_api_secret}' \
    -H 'Content-Type: application/json' \
    -d '{
            "upload": {
                "source_type": "thumbstrip_image", 
                "source_media_id": "{media_id}",
                "video_position": 10.0,
            },
            "relationships": {
                "media": [{"id": "{media_id}"}]
            }
        }'
```

After the uploading process has completed, make a GET /v2/sites/{site_id}/thumbnails/{thumbnail_id} call to retrieve the thumbnail transcoding status. Be sure to replace {thumbnail_id} with the id returned in the previous API response. When "status": "ready" is returned in the API call, continue to the next step.
```
curl -X GET "https://api.jwplayer.com/v2/sites/{site_id}/thumbnails/{thumbnail_id}" \
    -H 'Authorization: Bearer {v2_api_secret}' \
    -H 'Content-Type: application/json'
```

Make a PATCH /v2/sites/{site_id}/thumbnails/{thumbnail_id} call to promote the thumbnail to replace the current poster. In the JSON body, add "relationships.media[].is_poster": "true".
```
curl -X PATCH "https://api.jwplayer.com/v2/sites/{site_id}/thumbnails/{thumbnail_id}" \
    -H 'Authorization: Bearer {v2_api_secret}' \
    -H 'Content-Type: application/json' \
    -d '{
            "relationships": {
                "media": [{"id": "{media_id}", "is_poster": true}]
            }
        }'
```
📘
A media item can have only one static poster and one motion poster. Promoting a thumbnail to poster will demote the current poster for the media with the same thumbnail_type.

Delete a thumbnail

With the exception of a thumbnail that has been promoted to poster, you can delete any thumbnail resource from your account. that you do not plan to promote to a poster.

If the thumbnail you want to delete is the current poster, you must first promote another thumbnail to poster. This will allow you to delete the desired thumbnail. A poster image cannot be deleted.

❗️
A thumbnail cannot be recovered after it has been deleted.

Make a GET/v2/sites/{site_id}/media to list all media associated with a property. From the API response, retrieve the media_id of the media with which the thumbnail is associated.
```
curl -X GET "https://api.jwplayer.com/v2/sites/{site_id}/media" \
    -H 'Authorization: Bearer {v2_api_secret}' \
    -H 'Content-Type: application/json'
```

Make a GET /v2/sites/{site_id}/thumbnails?q=media_id:{media_id} to list all thumbnails associated with the media. From the API response, retrieve the thumbnail_id of the thumbnail you want to delete.
```
curl -X GET "https://api.jwplayer.com/v2/sites/{site_id}/thumbnails?q=media_id:{media_id}" \
    -H 'Authorization: Bearer {v2_api_secret}' \
    -H 'Content-Type: application/json'
```

Make a DELETE /v2/sites/{site_id}/thumbnails/{thumbnail_id} call.

🔑

Upload and promote a custom static or video poster

Standards

Implementation

📘

Create and promote a thumbnail from a media

💡

📘

Delete a thumbnail

❗️