---
title: thumbParams API (Thumbnail Templates)
url: https://docs.kaltura.com/docs/rich-media-cms-apis/content-management/thumbnail-thumbparams-api-thumbnail-templates
---

## thumbParams API (Thumbnail Templates)


The `thumbParams` service defines reusable thumbnail generation specifications that can be associated with conversion profiles for automatic thumbnail generation on upload.

### Actions

| Action | Description |
|--------|-------------|
| `thumbParams.add` | Create a new thumbnail params definition |
| `thumbParams.get` | Get by ID (includes system defaults) |
| `thumbParams.update` | Update params |
| `thumbParams.delete` | Soft-delete |
| `thumbParams.list` | List all params (includes system defaults from partner 0) |
| `thumbParams.getByConversionProfileId` | List params for a specific conversion profile |

### KalturaThumbParams Fields

| Field | Type | Range | Description |
|-------|------|-------|-------------|
| `cropType` | int | 1-6 | Resize mode (1-5 same as URL API type, plus 6=CROP_AFTER_RESIZE) |
| `quality` | int | 20-100 | JPEG quality |
| `width` | int | 0-10000 | Target width |
| `height` | int | 0-10000 | Target height |
| `cropX` | int | 0-10000 | Crop region X offset |
| `cropY` | int | 0-10000 | Crop region Y offset |
| `cropWidth` | int | 0-10000 | Crop region width |
| `cropHeight` | int | 0-10000 | Crop region height |
| `videoOffset` | float | ≥ 0 | Seconds into video to capture |
| `videoOffsetInPercentage` | int | 0-100 | Capture at percentage of video duration |
| `scaleWidth` | float | 0-10 | Scale multiplier for width |
| `scaleHeight` | float | 0-10 | Scale multiplier for height |
| `backgroundColor` | string | 1-6 hex | Background/padding color |
| `format` | string | — | Output format: `jpg`, `png`, `bmp` |
| `density` | int | ≥ 0 | Image DPI |
| `stripProfiles` | bool | — | Strip ICC profiles and comments |
| `interval` | int | ≥ 1 | Interval in seconds for periodic thumbnails |
| `sourceParamsId` | int | — | ID of source flavor/thumb params to capture from |

#### Additional Resize Mode (thumbParams only)

| Value | Name | Behavior |
|-------|------|----------|
| 6 | CROP_AFTER_RESIZE | Force-resize to dimensions, then crop. `cropX`/`cropY` control gravity: -1=NW/W/SW, 0=N/Center/S, 1=NE/E/SE |


```bash
# Create a "social card" thumbnail template
curl -X POST "$KALTURA_SERVICE_URL/service/thumbParams/action/add" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "thumbParams[objectType]=KalturaThumbParams" \
  -d "thumbParams[name]=Social Card 1200x630" \
  -d "thumbParams[width]=1200" \
  -d "thumbParams[height]=630" \
  -d "thumbParams[cropType]=3" \
  -d "thumbParams[quality]=90" \
  -d "thumbParams[videoOffsetInPercentage]=25"
```


**Business scenario — automatic thumbnail on upload:** Associate a thumbParams definition with a conversion profile. When new videos are uploaded, Kaltura automatically generates thumbnails at the configured dimensions, quality, and video offset — no additional API calls needed.