thumbAsset API (Stored Thumbnails) - Content Management

thumbAsset API (Stored Thumbnails)

The thumbAsset service manages persistent, editorial thumbnails attached to entries. Use when you need multiple thumbnails per entry, custom-uploaded images, or saved video frame captures.

Actions

Action	Description
`thumbAsset.add`	Create a thumb asset on an entry (QUEUED status)
`thumbAsset.setContent`	Upload image content to a thumb asset
`thumbAsset.addFromImage`	Create and upload in one call (file upload)
`thumbAsset.generate`	Capture a frame from video with inline params
`thumbAsset.generateByEntryId`	Capture using a stored thumbParams definition
`thumbAsset.regenerate`	Re-capture using existing params
`thumbAsset.setAsDefault`	Set which thumbnail displays for the entry
`thumbAsset.get`	Get a thumb asset by ID
`thumbAsset.list`	List all thumb assets for an entry
`thumbAsset.serve`	Serve the thumbnail image (with optional on-the-fly resize)
`thumbAsset.serveByEntryId`	Serve entry's default thumbnail (or by thumbParamsId)
`thumbAsset.getUrl`	Get download URL
`thumbAsset.update`	Update thumb asset metadata
`thumbAsset.delete`	Delete a thumb asset
`thumbAsset.export`	Export to remote storage
`thumbAsset.getRemotePaths`	Get remote storage paths

Upload a Custom Thumbnail

# Step 1: Create the thumb asset
curl -X POST "$KALTURA_SERVICE_URL/service/thumbAsset/action/add" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "entryId=$KALTURA_ENTRY_ID" \
  -d "thumbAsset[objectType]=KalturaThumbAsset" \
  -d "thumbAsset[tags]=custom,marketing"

# Step 2: Upload the image via upload token
curl -X POST "$KALTURA_SERVICE_URL/service/thumbAsset/action/setContent" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "id=$THUMB_ASSET_ID" \
  -d "contentResource[objectType]=KalturaUploadedFileTokenResource" \
  -d "contentResource[token]=$UPLOAD_TOKEN_ID"

Or upload directly with addFromImage:

curl -X POST "$KALTURA_SERVICE_URL/service/thumbAsset/action/addFromImage" \
  -F "ks=$KALTURA_KS" \
  -F "format=1" \
  -F "entryId=$KALTURA_ENTRY_ID" \
  -F "fileData=@custom_thumb.jpg"

Business scenario — marketing thumbnails: A content team uploads custom-designed thumbnails for featured videos (e.g., with text overlays, branded frames). These are stored as thumb assets and set as default using thumbAsset.setAsDefault.

Capture Frame from Video

# Capture with inline params
curl -X POST "$KALTURA_SERVICE_URL/service/thumbAsset/action/generate" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "entryId=$KALTURA_ENTRY_ID" \
  -d "thumbParams[objectType]=KalturaThumbParams" \
  -d "thumbParams[videoOffset]=30" \
  -d "thumbParams[width]=1280" \
  -d "thumbParams[height]=720" \
  -d "thumbParams[quality]=90"

# Capture using a stored thumbParams definition
curl -X POST "$KALTURA_SERVICE_URL/service/thumbAsset/action/generateByEntryId" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "entryId=$KALTURA_ENTRY_ID" \
  -d "destThumbParamsId=$THUMB_PARAMS_ID"

generate and generateByEntryId are restricted to VIDEO entries in ERROR_CONVERTING, PRECONVERT, or READY status.

Set Default Thumbnail

curl -X POST "$KALTURA_SERVICE_URL/service/thumbAsset/action/setAsDefault" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "thumbAssetId=$THUMB_ASSET_ID"

Sets this thumb asset as the entry's default thumbnail. Removes the default tag from all other thumb assets.

List Thumbnails for an Entry

curl -X POST "$KALTURA_SERVICE_URL/service/thumbAsset/action/list" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "filter[entryIdEqual]=$KALTURA_ENTRY_ID"

Delete a Thumbnail

curl -X POST "$KALTURA_SERVICE_URL/service/thumbAsset/action/delete" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "thumbAssetId=$THUMB_ASSET_ID"

To delete a thumb asset that is currently the default, first set a different thumb asset as default using thumbAsset.setAsDefault.

Serve with On-the-Fly Resize

# Serve with specific dimensions
curl -X POST "$KALTURA_SERVICE_URL/service/thumbAsset/action/serve" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "thumbAssetId=$THUMB_ASSET_ID" \
  -d "thumbParams[objectType]=KalturaThumbParams" \
  -d "thumbParams[width]=320" \
  -d "thumbParams[height]=180" \
  -d "thumbParams[cropType]=3"

Thumb Asset Statuses

Value	Name	Description
-1	ERROR	Generation failed
0	QUEUED	Created, waiting for content
1	CAPTURING	Frame capture in progress
2	READY	Available for serving
3	DELETED	Soft-deleted
4	NOT_APPLICABLE	N/A
7	IMPORTING	Content being imported
9	EXPORTING	Being exported to remote storage