Overview - Content Management
Thumbnail API Overview
This guide covers generating and managing thumbnails and images: the URL-based dynamic thumbnail API (31 parameters for on-the-fly resizing, cropping, format conversion, video frame extraction, and sprite sheet generation), the thumbAsset service for stored editorial thumbnails, and the thumbParams service for reusable thumbnail templates.
Base URL: https://www.kaltura.com/api_v3 (thumbAsset/thumbParams services); https://cdnapisec.kaltura.com (dynamic thumbnail URLs)
Auth: thumbAsset/thumbParams use -d "ks=$KALTURA_KS" form param. Dynamic thumbnail URLs work without KS for public entries; access-controlled entries require /ks/\{KS\} appended to the URL.
Format: Form-encoded request body; JSON response (format=1)
Prerequisites
- Kaltura account with a Partner ID (
$KALTURA_PARTNER_ID) - Admin KS (
$KALTURA_KS) for thumbAsset and thumbParams API calls (generate viasession.startor AppToken flow — see Session Guide) - Entry ID (
$KALTURA_ENTRY_ID) of a media entry in READY status (status=2) for frame capture operations - Service URL (
$KALTURA_SERVICE_URL) — defaults tohttps://www.kaltura.com/api_v3 - Dynamic thumbnail URLs require only the Partner ID and Entry ID; KS is needed only for access-controlled entries
When to Use
| Scenario | What to Use |
|---|---|
| Responsive thumbnails — Serve different sizes for different screen densities | Dynamic thumbnail URL with /width/W/height/H |
| Video timeline preview — Hover scrubber showing frames across the video | Sprite strip with /vid_slices/N |
| Specific video frame — Capture a frame at a known timestamp | /vid_sec/S parameter |
| Gallery grid — Uniform thumbnails with consistent dimensions | /type/3 (center crop) with fixed width/height |
| Letterboxed thumbnails — Preserve aspect ratio with padding | /type/2 with /bgcolor/HEX |
| High-quality download — Full-resolution PNG export | /width/1920/height/1080/quality/100/format/png |
| Custom editorial thumbnails — Upload marketing images per entry | thumbAsset.add + thumbAsset.setContent |
| Default thumbnail management — Control which thumbnail displays for an entry | thumbAsset.setAsDefault |
| Reusable thumbnail templates — Define standard thumbnail specs (e.g., "banner 1200x630") | thumbParams service |
| Region-of-interest crop — Crop a specific area from the source image | /src_x/X/src_y/Y/src_w/W/src_h/H |