---
title: Overview
url: https://docs.kaltura.com/docs/rich-media-cms-apis/content-management/thumbnail-overview
---

## 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 via `session.start` or AppToken flow — see [Session Guide](/docs/getting-started/authentication/ks-overview))  
- **Entry ID** (`$KALTURA_ENTRY_ID`) of a media entry in READY status (status=2) for frame capture operations  
- **Service URL** (`$KALTURA_SERVICE_URL`) — defaults to `https://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` |