thumbParams API (Thumbnail Templates) - Content Management

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

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