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 width 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 width of the posters.
  • posterFormat
    • jpeg (default) - Creates posters in JPEG format.
    • png - Creates posters in PNG format.
  • 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
  • version – (New in 4.1.0.) An optional version number. For creating thumbnails for older versions of the item essence. Default is latest version.
  • sourceTag – (New in 4.2.3.) 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.
Produces:

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.

Produces:
  • text/plain – CRLF-delimited list of thumbnail resource URIs
  • application/xml, application/jsonURIListDocument 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.

Produces:
  • text/plain – CRLF-delimited list of thumbnail resource URIs
  • application/xml, application/jsonURIListDocument 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/jsonURIListDocument 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/jsonURIListDocument 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-resource}

Returns thumbnail URIs on which further requests may be performed.

Query Parameters:
 
  • 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/jsonURIListDocument of thumbnail URIs

Insert thumbnail

PUT {thumbnail-resource-resource}/(time-code)

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 to insert
Status Codes:
  • 400 – Given data was not valid image/png

Remove all thumbnails

DELETE {thumbnail-resource-resource}

Remove all thumbnails handled by this resource.

Thumbnail handling

The following requests concern handling a specific thumbnail.

Get image representation

GET {thumbnail-resource}

Return the image representation of this thumbnail.

Produces:
  • image/png – Image of the thumbnail

Replace image representation

PUT {thumbnail-resource}

Set a new image representation for this thumbnail.

Accepts:
  • image/png – Image to insert
Status Codes:
  • 400 – Given data was not valid image/png

Remove thumbnail

DELETE {thumbnail-resource}

Remove this thumbnail.

Export thumbnail

POST {thumbnail-resource}/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/jsonJobDocuement