Skip to content

List an asset's subtitle tracks

GET
/assets/{id}/subtitle-tracks

Returns the subtitle and caption tracks attached to a video, audio or audiobook asset, sorted by language tag, or an empty array if it has none. Each track is a WebVTT file in storage; to read one, download it with GET /storage/objects/{hash} using its file_hash.

The list includes every track on the asset: uploaded ones and, if your instance runs AI transcription, the ones it made. AI tracks have the source_format whisper, which isn’t among the values listed below, and their confidence can be lower than 1. GET /assets/{id} returns the same tracks in its subtitle_tracks field.

Subtitles apply only to assets whose type is Video, Audio or Audiobook; the server goes by the type alone, not by the file. Another type gets a 422, and an unknown id or an asset in the trash a 404. Any signed-in account can list the tracks of any such asset; the asset’s access rules aren’t checked.

If the database fails while the asset is being checked, the server currently answers 200 with an empty body, not JSON, so treat an empty body as an error. Other server errors get a plain-text 500, not the JSON shown.

id
required
string format: uuid

The asset’s id.

The tracks, sorted by language tag. An empty array if there are none.

Array<object>

One subtitle or caption track. An asset has at most one per language; uploading another for the same language replaces it.

object
lang
required

The track’s language tag, such as en or fr-CA. und means the language couldn’t be worked out from the file name.

string
label

A display name, such as English (US) or Forced. Empty when none was given.

string
file_hash
required

The SHA-256 of the stored WebVTT file.

string
source_format
required

The format the track was uploaded in. It’s stored as WebVTT whatever the source format.

string
Allowed values: vtt srt ssa ass sub idx
confidence
required

How reliable the conversion to WebVTT is, from 0 to 1. Every format accepted today converts from text and gives 1; image-based subtitles, such as DVD IDX files, aren’t accepted yet.

number format: float
<= 1
created_at
string format: date-time

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Resource not found

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Request shape is valid but the action doesn’t apply (e.g. subtitles on a non-video/audio asset).

object
error
required

Human-readable error summary

string
Example
the request could not be completed