Create thumbnails for your website or app using the VIXY Thumbnail API

This article summarizes the possibilities of creating dynamic thumbnails, such as thumbnail slices for your website or app by using various parameters from our Thumbnail API service.

The VIXY API provides a special thumbnail service, aimed at simplifying the creation of thumbnails on-the-fly from video and image entries. 

The Thumbnail API provides simple means to dynamically transform (change size, cropping, etc.) image entries, and to generate images out of VIXY's video entries on the fly (while applying image transformations to the generated images).

The images are generated upon request (with caching via CDN) by calling the following URL format:{partner_id}/thumbnail/entry_id/{entry_id}

The result of the thumbnail API is an image with one or more of the following features:

  • A re-sized / cropped version of the original thumbnail image.
  • A specific frame from a video clip.
  • An older version of the entry thumbnail.
  • A various compression quality of the thumbnail image.

Using the Thumbnail API

  1. Replace {partner_id} with your account ID (you can find your partner ID by going to settings -> integration settings).
  2. Replace {entry_id} with the id of the desired entry thumbnail (Entry ID stands for video ID, the unique video number in VIXY).
  3. Then append any of the parameters below according to the following format:

Parameter Name Type Mandatory Description
entry_id string Yes The entry ID
widget_id string No The widget ID
version integer No The thumbnail version
width integer No Requested width in pixels
height integer No Requested height in pixels
type integer No Type of crop to be used – see remarks below
nearest_aspect_ratio boolean (1/0) No If 1, the image will be resized to nearest aspect ratio (based on the original image/video), and only then cropped to the desired dimensions. This will override the type parameter
bgcolor string No 6 hex digits web color code
quality string No JPEG quality for output (0-100). The default is 75
src_x integer No 1st part of a rectangle to take from original picture
src_y integer No 2nd part of a rectangle to take from original picture
src_w integer No 3rd part of a rectangle to take from original picture
src_h integer No 4th part of a rectangle to take from original picture
rel_width integer No Actual width of the image from which the src_* parameters were taken
rel_height integer No Actual height of the image from which the src_* parameters were taken
vid_sec float No The time to snap a frame from the video (to get a specific frame # use; second=frame/(durationSec * FPS)
vid_slice integer No Number of slice out of number of slices
vid_slices integer No Number of slices
start_sec float No The second (or part of second) to begin extracting the slices stripe from (e.g. to avoid black frame in videos that begin with fade to black, set start_sec to the second that is after the black transition). This param defaults to 0 if not set or invalid. If start_sec will be set to a higher number than end_sec, the API will return 404 error.
end_sec float No The second (or part of second) to stop extracting slices at (e.g. to create a stripe animation that is smooth but only contains few frames, use this parameter to only extract a short segment of your video instead of extracting slices across the entire video). This param defaults to the duration of the video if not provided or set to invalid value.
upload_token_id string No An ID of an uploadToken object representing a file that was recently uploaded (upload tokens are invalid after 2 weeks) to generate the image from
flavor_id integer No An ID of a specific video flavor to generate the image from
format string No Specify an output file format for the generated image. Supported values are: JPG, JPEG, JXR, PNG, PNG8/24/32/48/64, BMP, GIF, TIF, PSD, and PDF.
ks string No Kaltura Session string. Only mandatory if the account is configured to require session on thumbnails request
referrer string No base64 of a URL, use if entry’s thumbnail access control is set to force domain
file_name string No Used to specify a file name for the generated image. Must be the last parameter on the list to generate a URL that ends with a filename.extension

Example of a thumbnail URL that generates 20 slices of your video that can be used in a slideshow (or video preview on your site)

If you want to display a preview of the video on your website when people hover over the the thumbnail (also referred by our clients to us sometimes as the 'porn mode'), you can do this by creating a real-time slice of your videos existing of for example 20 to 50 slices:

The above request creates an image existing of 20 slices:


Entry ID: the video number out of your VIXY library

Width: the width in pixels

Vid_slices: the amount of video slices you want to generate

The next step is to render this image on your site by cutting it into 20 slices of 600 pixels width. 

Please be aware that requesting too many slices (>100) can cause a timeout error on our services as the request is too large. We advise to keep your amount of slices under 100 but preferrably 20 to 50. 

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us