Set a custom thumbnail

Replace a video's thumbnail with your own image or with a frame from the video. Send exactly one of:

• an image file as multipart form data in the image field, for example -F 'image=@cover.png'
• JSON { "url": "https://..." }, a public https link to an image, which the server downloads
• JSON { "seekSec": 12.5 }, to use the video frame at that many seconds from the start

The image must be JPEG, PNG or WebP and at most 10 MB. The server checks the file's content, not its name or declared type, so a GIF is refused. A url must be https and point to a public address, every redirect included. The server follows up to 3 redirects and gives up after 8 seconds.

A frame request answers 202 straight away and the frame is saved in the background. A seekSec past the end of the video uses the frame one second before the end. To follow it, poll GET /media/status/{mediaId} and read data.thumbnail: pending is true while the frame is being made, error says why it failed, and once it is saved url points to the new frame and source is custom. While a frame request for the video is still running, another one returns 409. A request that has not finished after 5 minutes no longer blocks a new one.

Each change replaces the current thumbnail and deletes the previous custom image. There is no way back to the automatic thumbnail. Only a video can have a thumbnail, and a frame cannot be taken from an archived video. You need permission to edit media.

Errors

• 400 when the request does not carry exactly one of image, url and seekSec: "Send exactly one of an image file, an https url or seekSec."
• 400 when url is not https or seekSec is below 0, with the validation message.
• 400 when the media is not a video: "Only a video can have a thumbnail."
• 400 when the image is not a JPEG, PNG or WebP file: "Use one JPEG, PNG or WebP image of up to 10 MB."
• 400 when the link is blocked or cannot be downloaded: "That image url could not be downloaded."
• 400 when a frame is asked of an archived video, or of one whose file Speak does not hold: "A frame cannot be taken from this video."
• 400 when the frame service refuses the request: "That frame could not be taken."
• 403 when you do not have permission to edit media.
• 404 when the media does not exist.
• 409 when a frame is already being taken for this video.
• 413 when the image is larger than 10 MB: "Use one JPEG, PNG or WebP image of up to 10 MB."
• 503 when the frame service is busy: "Thumbnails are busy right now. Try again in a minute."