Thumbnails [VC 21.3 GEN]

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 and thumbnailWidth. 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

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

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

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

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 or image/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