---
title: thumbAsset API (Stored Thumbnails)
url: https://docs.kaltura.com/docs/rich-media-cms-apis/content-management/thumbnail-thumbasset-api-stored-thumbnails
---

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


```bash
# 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`:**


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


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


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


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


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


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