---
title: Caption Asset CRUD
url: https://docs.kaltura.com/docs/rich-media-cms-apis/content-management/captions-caption-asset-crud
---

## Caption Asset CRUD


A `KalturaCaptionAsset` represents a subtitle or caption file attached to a media entry. Caption creation is a two-step process: first create the asset metadata (`captionAsset.add`), then upload the content (`captionAsset.setContent`).

### KalturaCaptionAsset Object

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Auto-generated asset ID (read-only) |
| `entryId` | string | Media entry this caption belongs to |
| `label` | string | Display label (e.g., "English", "Spanish CC") |
| `language` | string | Language from KalturaLanguage enum (e.g., `"English"`) |
| `languageCode` | string | ISO 639 code, auto-derived from language (read-only) |
| `format` | integer | Caption format: 1=SRT, 2=DFXP, 3=WebVTT, 4=CAP, 5=SCC (insertOnly) |
| `status` | integer | Asset status (see 3.2) |
| `isDefault` | boolean | Whether this is the default caption for the entry |
| `accuracy` | integer | Accuracy percentage (for machine-generated captions) |
| `displayOnPlayer` | boolean | Whether the player shows this caption track |
| `captionParamsId` | integer | Caption parameter template ID (insertOnly) |
| `source` | integer | Origin: `0`=UNKNOWN, `1`=ZOOM, `2`=WEBEX (insertOnly) |
| `parentId` | string | Parent caption asset ID (insertOnly, for derived captions) |
| `associatedTranscriptIds` | string | Comma-separated IDs of linked transcript assets |
| `usage` | integer | `0`=CAPTION, `1`=EXTENDED_AUDIO_DESCRIPTION |
| `size` | integer | File size in bytes (read-only) |
| `version` | integer | Version number (read-only) |
| `partnerId` | integer | Partner ID (read-only) |
| `createdAt` | integer | Unix timestamp (read-only) |
| `updatedAt` | integer | Unix timestamp (read-only) |
| `objectType` | string | Always `"KalturaCaptionAsset"` (read-only) |

### Caption Status Values

| Value | Name | Description |
|-------|------|-------------|
| -1 | ERROR | Processing error |
| 0 | QUEUED | Queued for processing |
| 2 | READY | Ready for use |
| 3 | DELETED | Soft-deleted |
| 7 | IMPORTING | Being imported from URL |
| 9 | EXPORTING | Being exported |

### Create Caption Asset


```
POST /service/caption_captionAsset/action/add
```



```bash
curl -X POST "$KALTURA_SERVICE_URL/service/caption_captionAsset/action/add" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "entryId=$KALTURA_ENTRY_ID" \
  -d "captionAsset[objectType]=KalturaCaptionAsset" \
  -d "captionAsset[label]=English" \
  -d "captionAsset[language]=English" \
  -d "captionAsset[format]=1" \
  -d "captionAsset[isDefault]=1"
```


| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `entryId` | string | Yes | Media entry ID |
| `captionAsset[objectType]` | string | Yes | Always `KalturaCaptionAsset` |
| `captionAsset[label]` | string | No | Display label |
| `captionAsset[language]` | string | Yes | Language (KalturaLanguage enum value) |
| `captionAsset[format]` | integer | No | `1`=SRT (default), `2`=DFXP, `3`=WEBVTT, `4`=CAP, `5`=SCC. insertOnly — set at creation time, remains fixed. |
| `captionAsset[isDefault]` | boolean | No | Set as default caption for the entry |
| `captionAsset[captionParamsId]` | integer | No | Template ID — language and label auto-copied from template |

**Response:** `KalturaCaptionAsset` object with generated `id` and `status=0` (QUEUED). The format defaults to SRT (1) if not specified.


```json
{
  "id": "1_abc123de",
  "entryId": "0_xyz789ab",
  "partnerId": 1234567,
  "label": "English",
  "language": "English",
  "languageCode": "en",
  "format": 1,
  "status": 0,
  "isDefault": true,
  "displayOnPlayer": true,
  "accuracy": 0,
  "size": 0,
  "version": 0,
  "createdAt": 1712620800,
  "updatedAt": 1712620800,
  "objectType": "KalturaCaptionAsset"
}
```


### Upload Content (Inline String)

After creating the asset, upload the caption content using `KalturaStringResource` for small files (<1 MB):


```bash
curl -X POST "$KALTURA_SERVICE_URL/service/caption_captionAsset/action/setContent" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "id=$CAPTION_ASSET_ID" \
  -d "contentResource[objectType]=KalturaStringResource" \
  --data-urlencode 'contentResource[content]=1
00:00:00,000 --> 00:00:05,000
Welcome to the presentation.

2
00:00:05,000 --> 00:00:10,000
Today we cover the Kaltura API.'
```


| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Caption asset ID (from `captionAsset.add`) |
| `contentResource[objectType]` | string | Yes | `KalturaStringResource` for inline content |
| `contentResource[content]` | string | Yes | Caption file content (URL-encode for special characters) |

**Response:** Updated `KalturaCaptionAsset` object. Status transitions to `2` (READY) after processing.


```json
{
  "id": "1_abc123de",
  "entryId": "0_xyz789ab",
  "partnerId": 1234567,
  "label": "English",
  "language": "English",
  "languageCode": "en",
  "format": 1,
  "status": 2,
  "isDefault": true,
  "displayOnPlayer": true,
  "size": 142,
  "version": 1,
  "createdAt": 1712620800,
  "updatedAt": 1712620860,
  "objectType": "KalturaCaptionAsset"
}
```


### Upload Content (Upload Token)

For larger files, use the three-step upload token flow:


```bash
# Step 1: Create upload token
curl -X POST "$KALTURA_SERVICE_URL/service/uploadToken/action/add" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "uploadToken[objectType]=KalturaUploadToken"

# Step 2: Upload file to token
curl -X POST "$KALTURA_SERVICE_URL/service/uploadToken/action/upload" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "uploadTokenId=$UPLOAD_TOKEN_ID" \
  -F "fileData=@captions.srt"

# Step 3: Attach to caption asset
curl -X POST "$KALTURA_SERVICE_URL/service/caption_captionAsset/action/setContent" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "id=$CAPTION_ASSET_ID" \
  -d "contentResource[objectType]=KalturaUploadedFileTokenResource" \
  -d "contentResource[token]=$UPLOAD_TOKEN_ID"
```


| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Caption asset ID (from `captionAsset.add`) |
| `contentResource[objectType]` | string | Yes | `KalturaUploadedFileTokenResource` for upload token |
| `contentResource[token]` | string | Yes | Upload token ID (from `uploadToken.upload`) |

See [Upload & Ingestion API](/docs/rich-media-cms-apis/content-management/upload-ingestion-overview) for upload token details.

### Upload Content (Remote URL)

Server fetches caption from a URL. Creates an async import job:


```bash
curl -X POST "$KALTURA_SERVICE_URL/service/caption_captionAsset/action/setContent" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "id=$CAPTION_ASSET_ID" \
  -d "contentResource[objectType]=KalturaUrlResource" \
  -d "contentResource[url]=https://example.com/captions/english.srt"
```


| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Caption asset ID (from `captionAsset.add`) |
| `contentResource[objectType]` | string | Yes | `KalturaUrlResource` for remote URL import |
| `contentResource[url]` | string | Yes | Direct URL to the caption file |

Status transitions to `7` (IMPORTING) during fetch, then `2` (READY) on completion.

### Get Caption Asset


```bash
curl -X POST "$KALTURA_SERVICE_URL/service/caption_captionAsset/action/get" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "captionAssetId=$CAPTION_ASSET_ID"
```


| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `captionAssetId` | string | Yes | Caption asset ID to retrieve |

**Response:** Full `KalturaCaptionAsset` object. Use to poll for status after `setContent`.

### List Caption Assets


```bash
curl -X POST "$KALTURA_SERVICE_URL/service/caption_captionAsset/action/list" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "filter[objectType]=KalturaAssetFilter" \
  -d "filter[entryIdEqual]=$KALTURA_ENTRY_ID"
```


| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `filter[objectType]` | string | Yes | `KalturaAssetFilter` or `KalturaCaptionAssetFilter` |
| `filter[entryIdEqual]` | string | Recommended | Filter by entry ID |
| `pager[pageSize]` | integer | No | Results per page (default 30, max 500) |
| `pager[pageIndex]` | integer | No | Page number (1-based, default 1) |

**Filter fields (`KalturaCaptionAssetFilter`):**

| Field | Description |
|-------|-------------|
| `entryIdEqual` / `entryIdIn` | Filter by entry ID (recommended) |
| `formatEqual` / `formatIn` | Filter by caption format |
| `statusEqual` / `statusIn` / `statusNotIn` | Filter by status |
| `captionParamsIdEqual` / `captionParamsIdIn` | Filter by template |
| `sizeGreaterThanOrEqual` / `sizeLessThanOrEqual` | Filter by file size |
| `createdAtGreaterThanOrEqual` / `createdAtLessThanOrEqual` | Date range |
| `updatedAtGreaterThanOrEqual` / `updatedAtLessThanOrEqual` | Date range |
| `tagsLike` | Tag-based search |
| `orderBy` | `+size`, `-size`, `+createdAt`, `-createdAt` |

**Response:**


```json
{
  "totalCount": 2,
  "objects": [
    {
      "id": "1_abc123",
      "entryId": "0_abc123",
      "label": "English",
      "language": "English",
      "languageCode": "en",
      "format": 1,
      "status": 2,
      "isDefault": true,
      "objectType": "KalturaCaptionAsset"
    }
  ],
  "objectType": "KalturaCaptionAssetListResponse"
}
```


### Update Caption Asset


```bash
curl -X POST "$KALTURA_SERVICE_URL/service/caption_captionAsset/action/update" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "id=$CAPTION_ASSET_ID" \
  -d "captionAsset[objectType]=KalturaCaptionAsset" \
  -d "captionAsset[label]=English (Corrected)"
```


| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Caption asset ID |
| `captionAsset[objectType]` | string | Yes | Always `KalturaCaptionAsset` |
| `captionAsset[label]` | string | No | Updated label |
| `captionAsset[language]` | string | No | Updated language |
| `captionAsset[isDefault]` | boolean | No | Update default status |

**Response:** Updated `KalturaCaptionAsset` object.


```json
{
  "id": "1_abc123de",
  "entryId": "0_xyz789ab",
  "partnerId": 1234567,
  "label": "English (Corrected)",
  "language": "English",
  "languageCode": "en",
  "format": 1,
  "status": 2,
  "isDefault": true,
  "displayOnPlayer": true,
  "size": 142,
  "version": 2,
  "createdAt": 1712620800,
  "updatedAt": 1712621400,
  "objectType": "KalturaCaptionAsset"
}
```


The `format` field is insertOnly — set it at creation time, as it remains fixed for the lifetime of the asset.

### Set as Default Caption


```bash
curl -X POST "$KALTURA_SERVICE_URL/service/caption_captionAsset/action/setAsDefault" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "captionAssetId=$CAPTION_ASSET_ID"
```


| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `captionAssetId` | string | Yes | Caption asset ID to set as default |

Marks this caption asset as the default for its entry. Automatically unsets the previous default. Returns no response body on success.

### Delete Caption Asset


```bash
curl -X POST "$KALTURA_SERVICE_URL/service/caption_captionAsset/action/delete" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "captionAssetId=$CAPTION_ASSET_ID"
```


| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `captionAssetId` | string | Yes | Caption asset ID to delete |

Returns no response body on success. The caption asset status transitions to `3` (DELETED).