Thumbnails¶
Creating thumbnails and posters¶
Thumbnails and posters can be created by starting a thumbnail job.
Create 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.
Changed in version 5.0: For multi-layer PSD/PSB files, only a thumbnail of all layers flattened will be generated by default.
Query Parameters: - createThumbnails (boolean) –
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 (string) – A list of time codes to use for creating posters.
- thumbnailWidth (integer) – The width of the thumbnails. If
thumbnailWidth
is specified,thumbnailHeight
must also be specified. - thumbnailHeight (integer) – The height of the thumbnails. If
thumbnailHeight
is specified,thumbnailWidth
must also be specified. - thumbnailPeriod (string) – 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 (integer) – The width of the posters.
- posterHeight (integer) – The height of the posters.
- posterFormat (string) –
jpeg
(default) - Creates posters in JPEG format.png
- Creates posters in PNG format.
- thumbnailService (string) – Identifies which thumbnail resource that should be used.
- tag (string) – Include additional video settings from this transcode preset. Resolution settings in the tag are overridden by query parameters
thumbnailHeight
andthumbnailWidth
. - version (integer) – A version number. For creating thumbnails for older versions of the item essence. Default is latest version.
- sourceTag (string) – 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.
- resourceId (string) – The transcoder resource to use to execute the transcode.
- notification (string) – The placeholder job notification to use for this job.
- notificationData (string) – Any additional data to include for notifications on this job.
- priority (string) – The priority to assign to the job. Default is
MEDIUM
. - jobmetadata (string[]) – Additional information for the job task.
Produces: - application/xml, application/json – JobDocument
Role: _job_write
- createThumbnails (boolean) –
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.
List thumbnail 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 (integer) – 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
-
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 (integer) – 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
Update or create a thumbnail resource 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
-
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.
Get a thumbnail sprite sheet for an item¶
New in version 5.6.
A thumbnail sprite sheet is a large image containing all of the thumbnails for an item, together with information about each thumbnail.
-
GET
/item/
(item-id)/thumbnail/spritesheet
¶ Returns a thumbnail sprite sheet which contains a URI to the generated sprite sheet and the positions of the images.
Query Parameters: - noauth-url (boolean) –
true
Return URIs that do not need authentication.false
(default) Return normal URIs
Request Headers: - If-Modified-None – Optional header containing ETag of previous call. If no changes to thumbnails have been done, a 304 Not Modified is returned.
Response Headers: - ETag – Contains the computed ETag of the response.
Produces: - application/xml – ThumbnailSpriteSheetDocument
- text/vtt – The sheet in WebVTT form
- noauth-url (boolean) –
Thumbnail resource handling¶
The following requests deal with managing collections of thumbnail URIs for a specific thumbnail resource.
List all thumbnails¶
-
GET
{thumbnail-resource}
¶ Returns thumbnail URIs on which further requests may be performed.
Query Parameters: - url (boolean) –
true
- Return list of URLs.false
(default) - Return list of ids.
- noauth-url (boolean) –
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 (boolean) –
Update or create a 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
Delete 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.
Retrieve the image representation¶
-
GET
{thumbnail-resource}/
(time)¶ Return the image representation of this thumbnail.
Query Parameters: - hash (string) – The checksum of the image.
- type (string) – Optional type.
Produces: - image/png, image/jpeg – Image of the thumbnail
Role: _thumbnail_read
Delete a thumbnail¶
-
DELETE
{thumbnail-resource}/
(time)¶ Remove this thumbnail.
Role: _thumbnail_write
Export a thumbnail¶
-
POST
{thumbnail-resource}/
(time)/export
¶ Starts a job that writes the thumbnail or poster to a specific destination.
Query Parameters: - uri (string) – Required. URI of export location of thumbnail or poster
- format (string) – Image format of destination. E.g.
tiff
. - notification (string) – The placeholder job notification to use for this job.
- notificationData (string) – Any additional data to include for notifications on this job.
- priority (string) – The priority to assign to the job. Default is
MEDIUM
. - jobmetadata (string[]) – Additional information for the job task.
Produces: - application/xml, application/json – JobDocument
Role: _thumbnail_read