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 |
|
Image Dimensions | 1920x1080 |
A custom video poster should adhere to the following standards.
Item | Details |
---|---|
Accepted File Formats |
|
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 athumbnail
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 theupload.method
,upload.thumbnail_type
, andrelationships.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 theupload_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 athumbnail
resource to contain the poster image. Before being promoted, all potential poster images are stored as thumbnails.
Within the JSON object, you must specify theupload.source_type
,upload.source_media_id
, andupload.video_position
orupload.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 theid
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
.
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.
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 thethumbnail_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.