Serving Captions - Content Management

Serving Captions

Serve Raw

Returns the caption content in its original format (SRT, DFXP, etc.):

curl "$KALTURA_SERVICE_URL/service/caption_captionAsset/action/serve?ks=$KALTURA_KS&captionAssetId=$CAPTION_ASSET_ID"

Parameter	Type	Required	Description
captionAssetId	string	Yes	Caption asset ID to serve

Returns a redirect to the CDN URL. Follow the redirect to get the raw content. The response Content-Type matches the caption format.

Serve as WebVTT

Converts any caption format to WebVTT on the fly. Supports HLS segmented delivery:

# Get HLS M3U8 playlist (segmentIndex omitted or null)
curl "$KALTURA_SERVICE_URL/service/caption_captionAsset/action/serveWebVTT?ks=$KALTURA_KS&captionAssetId=$CAPTION_ASSET_ID"

# Get a specific WebVTT segment
curl "$KALTURA_SERVICE_URL/service/caption_captionAsset/action/serveWebVTT?ks=$KALTURA_KS&captionAssetId=$CAPTION_ASSET_ID&segmentIndex=0"

Parameter	Type	Default	Description
captionAssetId	string	—	Caption asset ID
segmentDuration	integer	30	Duration of each segment in seconds
segmentIndex	integer	null	Segment number. null returns M3U8 playlist (application/x-mpegurl). Integer returns WebVTT segment (text/vtt).
localTimestamp	integer	10000	Local timestamp offset

HLS delivery flow:

1. Player requests M3U8 manifest via serveWebVTT (no segmentIndex)
2. Response is an HLS playlist with segment URLs
3. Player fetches individual WebVTT segments as needed

Serve as JSON

Returns structured JSON with timestamps in milliseconds. Ideal for AI/LLM integrations, RAG pipelines, and programmatic caption analysis:

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

Parameter	Type	Required	Description
captionAssetId	string	Yes	Caption asset ID to serve as JSON

Response:

{
  "objects": [
    {
      "startTime": 0,
      "endTime": 5000,
      "content": [{"text": "Welcome to the presentation."}]
    },
    {
      "startTime": 5000,
      "endTime": 10000,
      "content": [{"text": "Today we cover the Kaltura API."}]
    }
  ]
}

Times are in milliseconds. Maximum source file size: 1 MB. For larger files, use serve or serveWebVTT.

Serve by Entry ID

Serve the default caption for an entry without looking up the caption asset ID:

curl "$KALTURA_SERVICE_URL/service/caption_captionAsset/action/serveByEntryId?ks=$KALTURA_KS&entryId=$KALTURA_ENTRY_ID"

Parameter	Type	Required	Description
entryId	string	Yes	Media entry ID
captionParamId	integer	No	Target a specific template instead of the default

Returns raw caption content for the entry's default caption asset. If no default caption exists, the call returns an error.

Get Download URL

curl -X POST "$KALTURA_SERVICE_URL/service/caption_captionAsset/action/getUrl" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "id=$CAPTION_ASSET_ID"

Parameter	Type	Required	Description
id	string	Yes	Caption asset ID
storageId	integer	No	Storage profile ID (for multi-CDN setups)

Response: A direct CDN download URL string (JSON-encoded):

"https://cfvod.kaltura.com/api_v3/service/caption_captionAsset/action/serve/captionAssetId/1_abc123de/ks/..."

Use getUrl + HTTP fetch for server-side consumption — serve returns a redirect which requires follow-redirect handling.