Thumbnails¶
Creating thumbnails and posters¶
Thumbnails and posters can be created by starting a thumbnail job.
Start a thumbnail job¶
-
POST
/item/
(item-id)/thumbnail
¶ Creates a new thumbnail job with the specified parameters. Note that a job cannot both create thumbnails at specified intervals and posters. Creating thumbnails according to transcoder rules and creating posters is however allowed.
Query Parameters: - createThumbnails –
true
- Creates thumbnails according to default transcoder rules.- t1, ... - Thumbnails will be created on the specified, comma-separated, Time codes.
false
(default) - No thumbnails will be created.
- createPosters – An optional list of Time codes to use for creating posters.
- thumbnailWidth – An optional integer specifying the width of the thumbnails.
- thumbnailHeight – An optional integer specifying the height of the thumbnails.
- thumbnailPeriod – An optional timecode string specifying the interval of the thumbnails. It should be a decimal integer when working with multi-page images/PDFs, meaning every N page(s).
- posterWidth – An optional integer specifying the width of the posters.
- posterHeight – An optional integer specifying the height of the posters.
- posterFormat –
jpeg
(default) - Creates posters in JPEG format.png
- Creates posters in PNG format.
- thumbnailService – An optional identifier to which thumbnail resource that should be used.
- tag – Include additional video settings from this transcode preset.
- version – An optional version number. For creating thumbnails for older versions of the item essence. Default is latest version.
- sourceTag –
Optional comma separated shape tags. The fist valid shape will be chosen as the source of the job. If non of the tags are valid, the original shape will be used.
New in version 4.2.3.
- notification – See Notifications . (Optional)
- notificationData – See Notifications . (Optional)
- priority – The priority to assign to the job. Default is
MEDIUM
. - jobmetadata – Additional information for the job task. See Special job metadata values
Produces: - application/xml, application/json – JobDocument
- createThumbnails –
Example¶
Creating thumbnails according to transcoder rules and posters at the time codes 50@PAL and 100@PAL.
POST /item/VX-123/thumbnail?createThumbnails=true&createPosters=50@PAL,100@PAL&sourceTag=mov,mp4
<JobDocument xmlns="http://xml.vidispine.com/schema/vidispine">
<jobId>VX-1219</jobId>
<user>admin</user>
<started>2010-04-23T11:24:24.434+02:00</started>
<status>READY</status>
<type>THUMBNAIL</type>
<priority>MEDIUM</priority>
</JobDocument>
Item thumbnail resources¶
The following requests deal with managing thumbnail resources for specific items.
Get resources for an item¶
-
GET
/item/
(item-id)/thumbnailresource
¶ Return one or more poster resource URIs which can be used to manage the thumbnails for a specific item.
Query Parameters: - version – Return thumbnails from this essence version. By default thumbnails for the latest version will be returned.
Produces: - text/plain – CRLF-delimited list of thumbnail resource URIs
- application/xml, application/json – URIListDocument of thumbnail resource URIs
New in version 4.2.
-
GET
/item/
(item-id)/posterresource
¶ Return one or more poster resource URIs which can be used to manage the posters for a specific item.
Query Parameters: - version – Return posters from this essence version. By default posters for the latest version will be returned.
Produces: - text/plain – CRLF-delimited list of thumbnail resource URIs
- application/xml, application/json – URIListDocument of thumbnail resource URIs
Put resources for an item¶
-
PUT
/item/
(item-id)/thumbnailresource
¶ If no thumbnail resources are defined for an item, create a resource and return it.
Produces: - text/plain – CRLF-delimited list of thumbnail resource URIs
- application/xml, application/json – URIListDocument of thumbnail resource URIs
New in version 4.2.
-
PUT
/item/
(item-id)/posterresource
¶ If no poster resources are defined for an item, create a resource and return it.
Produces: - text/plain – CRLF-delimited list of thumbnail resource URIs
- application/xml, application/json – URIListDocument of thumbnail resource URIs
Note
Thumbnails and posters for an item share the same resource. Hence, if a resource is added for posters, it is automatically added for thumbnails as well.
Thumbnail resource handling¶
The following requests deal with managing collections of thumbnail URIs for a specific thumbnail resource.
Get list of thumbnails¶
-
GET
{thumbnail-resource}
¶ Returns thumbnail URIs on which further requests may be performed.
Query Parameters: - url –
true
- Return list of URLs.false
(default) - Return list of ids.
- noauth-url –
true
Return URIs that do not need authentication.false
(default) Return normal URIs
Produces: - text/plain – CRLF-delimited list of thumbnail URIs.
- application/xml, application/json – URIListDocument of thumbnail URIs
Role: _thumbnail_read
- url –
Insert or update thumbnail¶
-
PUT
{thumbnail-resource}/
(time)¶ Create a new thumbnail at the specified time code. If a thumbnail with the specified time code already exists it is replaced.
Accepts: - image/png, image/jpeg – Image to insert
Produces: - text/plain – Informational status message.
Status Codes: - 400 – Given data was not valid
image/png
orimage/jpeg
Role: _thumbnail_write
Remove all thumbnails¶
-
DELETE
{thumbnail-resource}
¶ Remove all thumbnails handled by this resource.
Role: _thumbnail_write
Thumbnail handling¶
The following requests concern handling a specific thumbnail.
Get image representation¶
-
GET
{thumbnail-resource}/
(time)¶ Return the image representation of this thumbnail.
Produces: - image/png, image/jpeg – Image of the thumbnail
Role: _thumbnail_read
Remove thumbnail¶
-
DELETE
{thumbnail-resource}/
(time)¶ Remove this thumbnail.
Role: _thumbnail_write
Export thumbnail¶
-
POST
{thumbnail-resource}/
(time)/export
¶ Query Parameters: - uri – Mandatory URI of export location of thumbnail or poster
- format – Optional image format of destination. E.g.
tiff
. - notification – See Notifications . (Optional)
- notificationData – See Notifications . (Optional)
- priority – The priority to assign to the job. Default is
MEDIUM
. - jobmetadata – Additional information for the job task. See Special job metadata values
Produces: - application/xml, application/json – JobDocument
Role: _thumbnail_read