Caption Asset CRUD - Content Management

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

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.

{
  "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):

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.

{
  "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:

# 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 for upload token details.

Upload Content (Remote URL)

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

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

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

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:

{
  "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

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.

{
  "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

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

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