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:
https://platform.vixyvideo.com/p/{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
- Replace {partner_id} with your account ID (you can find your partner ID by going to settings -> integration settings).
- Replace {entry_id} with the id of the desired entry thumbnail (Entry ID stands for video ID, the unique video number in VIXY).
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:
https://platform.vixyvideo.com/p/600/thumbnail/version/1000/entry_id/0_ybdcfclh/width/600/vid_slices/20
The above request creates an image existing of 20 slices:
Whereas:
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.