Skip to main content
View as Markdown

Dynamic Thumbnail API (URL-Based) - Content Management

Dynamic Thumbnail API (URL-Based)​

Generate thumbnails on the fly via URL parameters. Results are CDN-cached (1 hour for ready entries, 30 days in memcache) — use freely for responsive UIs and per-request customization.

URL pattern:

https://cdnapisec.kaltura.com/p/\{PARTNER_ID\}/thumbnail/entry_id/\{ENTRY_ID\}/{param}/{value}/...

Dimensions and Resize​

ParameterTypeDefaultRangeDescription
/width/\{W\}int1200-10000Output width in pixels. If omitted with height, auto-calculates preserving aspect ratio. Default 120 when both omitted
/height/\{H\}int900-10000Output height in pixels. If omitted with width, auto-calculates preserving aspect ratio. Default 90 when both omitted
/def_width/\{W\}float-1-1 to 10000Override the 120px default width when both width and height are omitted
/def_height/\{H\}float-1-1 to 10000Override the 90px default height when both width and height are omitted
/type/\{T\}int11-5Resize mode (see Resize Modes below)
/density/\{D\}float00+Image DPI. 0 = use partner default

Resize Modes (type parameter)​

ValueNameBehavior
1RESIZEResize maintaining aspect ratio. If only one dimension given, the other scales proportionally
2RESIZE_WITH_PADDINGFit within dimensions, pad remaining space with bgcolor
3CROPCenter-crop to fill dimensions (may clip edges). Best for uniform grids
4CROP_FROM_TOPLike crop but anchored to top. Best for portraits and posters
5RESIZE_WITH_FORCEForce-resize to exact dimensions, ignoring aspect ratio (may distort)

Business scenario — responsive gallery: A video catalog displays thumbnails at different sizes: 320x180 for mobile grid, 640x360 for desktop hover, 160x90 for search results. Each size is a different URL — the CDN caches each variant independently.

Output Format and Quality​

ParameterTypeDefaultDescription
/quality/\{Q\}int0JPEG quality (0-100). 0 = use partner default
/format/\{F\}stringjpgOutput format: jpg, png, bmp, gif
/bgcolor/\{HEX\}stringffffffBackground color for padding (6 hex chars, e.g., ff0000)
/strip/\{S\}string—Strip ICC color profiles and metadata. Null = use partner default
/nearest_aspect_ratio/{0|1}int0When 1, selects the thumbAsset with the closest aspect ratio, then crops to fit

Video Frame Extraction​

ParameterTypeDefaultDescription
/vid_sec/\{S\}float-1Capture frame at specific second. Capped to entry duration (out-of-range values clamp to last second)
/vid_slice/\{N\}int-1Extract slice N from a sprite strip (0-based, use with vid_slices)
/vid_slices/\{TOTAL\}int-1Divide video into TOTAL equal segments. When vid_slice=-1, generates a horizontal sprite strip of all slices
/start_sec/\{S\}float-1Start of time range for sprite strips (must be ≤ end_sec)
/end_sec/\{S\}float-1End of time range for sprite strips

Sprite strip constraint: width × vid_slices and height × vid_slices must each be < 65,500 pixels.

Business scenario — video timeline scrubber: A player shows frame previews when the user hovers over the progress bar. Generate a single sprite strip image with /vid_slices/20/width/160/height/90, then use CSS background-position to show the correct frame on hover. One HTTP request serves all 20 preview frames.

Source Crop (Region of Interest)​

ParameterTypeDefaultRangeDescription
/src_x/\{X\}float00-10000Source crop X offset
/src_y/\{Y\}float00-10000Source crop Y offset
/src_w/\{W\}float00-10000Source crop width
/src_h/\{H\}float00-10000Source crop height
/rel_width/\{W\}float-1-1 to 10000Reference width for coordinate normalization
/rel_height/\{H\}float-1-1 to 10000Reference height for coordinate normalization

Coordinate normalization: If your crop coordinates are measured against a display size different from the original image (e.g., a 1280x720 preview pane showing a 1920x1080 image), use rel_width and rel_height to specify the coordinate system. The server automatically scales src_* values to match the original image dimensions.

Business scenario — face-centered crop: An image editor lets users draw a crop rectangle on a preview canvas. The canvas is 640x360 but the original image is 4000x2250. Send src_x/120/src_y/80/src_w/400/src_h/200/rel_width/640/rel_height/360 — the server scales the coordinates to the full-resolution image.

Source and Access​

ParameterTypeDescription
/flavor_id/\{ID\}stringGenerate thumbnail from a specific flavor (transcoded rendition)
/flavor_params_id/\{ID\}stringUse dimensions from a flavor params definition instead of explicit width/height
/upload_token_id/\{ID\}stringGenerate thumbnail from an in-progress upload token (preview before entry creation)
/version/\{V\}intSpecific thumbnail version (0-10M)
/crop_provider/\{NAME\}stringCustom crop provider plugin
/ks/\{KS\}stringKaltura Session for access-controlled entries
/referrer/\{BASE64\}stringBase64-encoded referrer for domain restrictions
/file_name/\{NAME\}stringDownload filename (must be the last parameter in the URL)

Examples​

# Default thumbnail (120x90)
https://cdnapisec.kaltura.com/p/$KALTURA_PARTNER_ID/thumbnail/entry_id/$KALTURA_ENTRY_ID

# Responsive: 640x360, center-cropped, at 30 seconds
https://cdnapisec.kaltura.com/p/$KALTURA_PARTNER_ID/thumbnail/entry_id/$KALTURA_ENTRY_ID/width/640/height/360/type/3/vid_sec/30

# High-quality PNG for export
https://cdnapisec.kaltura.com/p/$KALTURA_PARTNER_ID/thumbnail/entry_id/$KALTURA_ENTRY_ID/width/1920/height/1080/quality/100/format/png

# CSS sprite strip: 10 slices for hover preview
https://cdnapisec.kaltura.com/p/$KALTURA_PARTNER_ID/thumbnail/entry_id/$KALTURA_ENTRY_ID/width/160/height/90/vid_slices/10

# Padded with white background (letterboxed)
https://cdnapisec.kaltura.com/p/$KALTURA_PARTNER_ID/thumbnail/entry_id/$KALTURA_ENTRY_ID/width/400/height/400/type/2/bgcolor/ffffff

# Sprite strip from specific time range (10s to 60s)
https://cdnapisec.kaltura.com/p/$KALTURA_PARTNER_ID/thumbnail/entry_id/$KALTURA_ENTRY_ID/width/160/height/90/vid_slices/10/start_sec/10/end_sec/60

# Individual slice from a sprite (slice 3 of 10)
https://cdnapisec.kaltura.com/p/$KALTURA_PARTNER_ID/thumbnail/entry_id/$KALTURA_ENTRY_ID/width/160/height/90/vid_slices/10/vid_slice/3

# Region-of-interest crop
https://cdnapisec.kaltura.com/p/$KALTURA_PARTNER_ID/thumbnail/entry_id/$KALTURA_ENTRY_ID/src_x/100/src_y/50/src_w/800/src_h/450/width/400/height/225

# Social media share card (1200x630, padded)
https://cdnapisec.kaltura.com/p/$KALTURA_PARTNER_ID/thumbnail/entry_id/$KALTURA_ENTRY_ID/width/1200/height/630/type/2/bgcolor/000000/quality/90

# Force exact dimensions (stretch)
https://cdnapisec.kaltura.com/p/$KALTURA_PARTNER_ID/thumbnail/entry_id/$KALTURA_ENTRY_ID/width/300/height/300/type/5

# Download as file
https://cdnapisec.kaltura.com/p/$KALTURA_PARTNER_ID/thumbnail/entry_id/$KALTURA_ENTRY_ID/width/1920/height/1080/file_name/thumbnail.jpg

# Access-controlled entry
https://cdnapisec.kaltura.com/p/$KALTURA_PARTNER_ID/thumbnail/entry_id/$KALTURA_ENTRY_ID/width/640/height/360/ks/$KALTURA_KS

Behavior Notes​

  • KS is optional for public entries. The endpoint auto-detects the partner from the entry ID.
  • Image entries (mediaType=2): The original uploaded image is used as the thumbnail source. vid_sec, vid_slice, and vid_slices apply only to video entries.
  • Audio entries: Return a generic audio placeholder unless the partner has configured a custom audioThumbEntryId.
  • Deleted entries: Return an ENTRY_DELETED_MODERATED error.
  • Caching: Ready entries are cached for 1 hour (CDN) and 30 days (memcache). Non-ready entries are cached for 60 seconds. Access-controlled entries disable caching.
  • vid_sec capping: Values beyond the entry duration are clamped to the last second gracefully.
  • EXIF orientation: Images are auto-rotated based on EXIF Orientation tags before crops/resizes.
  • Animated GIF: Partners with supportAnimatedThumbnails enabled preserve GIF animation in output.
  • Concurrent generation limit: The server limits parallel ImageMagick processes. Extremely high-traffic burst requests for uncached thumbnails may get TOO_MANY_PROCESSES errors — these are transient and resolve on retry.