---
title: Dynamic Thumbnail API (URL-Based)
url: https://docs.kaltura.com/docs/rich-media-cms-apis/content-management/thumbnail-dynamic-thumbnail-api-url-based
---

## 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

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

#### Resize Modes (`type` parameter)

| Value | Name | Behavior |
|-------|------|----------|
| 1 | RESIZE | Resize maintaining aspect ratio. If only one dimension given, the other scales proportionally |
| 2 | RESIZE_WITH_PADDING | Fit within dimensions, pad remaining space with `bgcolor` |
| 3 | CROP | Center-crop to fill dimensions (may clip edges). Best for uniform grids |
| 4 | CROP_FROM_TOP | Like crop but anchored to top. Best for portraits and posters |
| 5 | RESIZE_WITH_FORCE | Force-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

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `/quality/\{Q\}` | int | 0 | JPEG quality (0-100). 0 = use partner default |
| `/format/\{F\}` | string | jpg | Output format: `jpg`, `png`, `bmp`, `gif` |
| `/bgcolor/\{HEX\}` | string | ffffff | Background 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}` | int | 0 | When 1, selects the thumbAsset with the closest aspect ratio, then crops to fit |

### Video Frame Extraction

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

| Parameter | Type | Default | Range | Description |
|-----------|------|---------|-------|-------------|
| `/src_x/\{X\}` | float | 0 | 0-10000 | Source crop X offset |
| `/src_y/\{Y\}` | float | 0 | 0-10000 | Source crop Y offset |
| `/src_w/\{W\}` | float | 0 | 0-10000 | Source crop width |
| `/src_h/\{H\}` | float | 0 | 0-10000 | Source crop height |
| `/rel_width/\{W\}` | float | -1 | -1 to 10000 | Reference width for coordinate normalization |
| `/rel_height/\{H\}` | float | -1 | -1 to 10000 | Reference 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

| Parameter | Type | Description |
|-----------|------|-------------|
| `/flavor_id/\{ID\}` | string | Generate thumbnail from a specific flavor (transcoded rendition) |
| `/flavor_params_id/\{ID\}` | string | Use dimensions from a flavor params definition instead of explicit width/height |
| `/upload_token_id/\{ID\}` | string | Generate thumbnail from an in-progress upload token (preview before entry creation) |
| `/version/\{V\}` | int | Specific thumbnail version (0-10M) |
| `/crop_provider/\{NAME\}` | string | Custom crop provider plugin |
| `/ks/\{KS\}` | string | Kaltura Session for access-controlled entries |
| `/referrer/\{BASE64\}` | string | Base64-encoded referrer for domain restrictions |
| `/file_name/\{NAME\}` | string | Download filename (must be the last parameter in the URL) |

### Examples


```bash
# 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.