Skip to main content

Upload Custom Thumbnail

POST 
/api/v1/assets/:asset_id/thumbnail

Replace an asset's automatically generated thumbnail with your own image.

By default FileSpin generates an asset's thumbnail from the file itself. Use this API when the automatic thumbnail is a poor representation of the asset — a dark video frame, an uninformative first page, or a product shot where the wrong detail is in view.

The uploaded image is stored as the asset's smart-image (on-demand image) rendition and marked as user-provided. The media pipeline never regenerates over a user-provided thumbnail, so your image survives an original replace and any reprocessing of the asset. Call Revert Custom Thumbnail to go back to the automatic one.

For a video, you can use one of its storyboard frames instead of uploading an image: see Set Thumbnail from Storyboard.

HTTP REQUEST​

Upload the image as multipart/form-data. Use file as the form field name.

KeyValueDescription
ASSET_IDstringAsset ID, 32 character alphanumeric UUID
filebinaryThe thumbnail image to upload

Accepted types: image/jpeg, image/png, image/webp. Clients that send a generic content type (e.g. application/octet-stream) fall back to the filename extension before being rejected.

Maximum size: 10 MB.

HTTP RESPONSE​

Returns 202 — the thumbnail is processed asynchronously. Note addons_info.ON_DEMAND_IMAGE.version from Get Data before the call, then poll until user_provided is true and version is higher; that is the signal the new thumbnail is live. Checking user_provided alone is not enough when the asset already has a custom thumbnail — it is true before your new image lands.

Existing ODI URLs can keep showing the previous thumbnail for a while because of CDN and browser caching. Add the new version to the URL as v to show it straight away: see Showing an updated thumbnail.

Request​

Responses​

Thumbnail accepted and queued. Poll /data until addons_info.ON_DEMAND_IMAGE.user_provided is true and its version is higher than before the call.