Skip to content

Upload a subtitle track

POST
/assets/{id}/subtitle-tracks

Adds a subtitle or caption track to a video, audio or audiobook asset, or replaces its track in the same language. The file’s text goes in a JSON body; the server converts it to WebVTT, stores it and answers 202 with the finished track. Nothing is queued.

For example: {"lang": "en", "label": "English", "source_format": "srt", "content": "1\n00:00:01,000 --> 00:00:03,500\nHello.\n"}

What happens to each format:

  • vtt: must start with WEBVTT (a leading byte order mark is removed); the rest is stored as sent, without checking the cues.
  • srt: commas in the timing lines become full stops, and lines that are only a number are dropped.
  • ssa and ass: only the Dialogue lines of the [Events] section are kept, without styling; lines the converter can’t read are skipped.
  • sub (MicroDVD): frame numbers are read at 24 frames per second, whatever the video’s frame rate. For another rate, convert the file to WebVTT first.
  • idx (DVD image subtitles) isn’t supported and gets a 501 with no body.

An srt, ssa, ass or sub file with no cues the converter can read gets a 400, and so does an unknown format. A converted track gets confidence 1. That says the text was converted, not that its timing or wording was checked.

A track is identified by its asset and its exact lang, so en and EN are two tracks. Uploading again in the same language replaces the file, format and label and resets created_at; leave out label and it becomes empty. The last write wins, including one from AI transcription, if your instance runs it. The replaced file stays in storage; the server doesn’t delete stored bytes at the moment.

lang has to look like a language tag, such as en, en-US or zh-Hant-TW, or be und for unknown. Only that shape is checked: 1 to 8 letters, then up to four more parts of 1 to 8 letters or digits, each after a hyphen. The tag is stored as sent, not normalised or looked up.

Subtitles apply only to assets whose type is Video, Audio or Audiobook; another type gets a 422, and an unknown id or an asset in the trash a 404. Any signed-in account can add or replace tracks on any such asset; ownership and edit rights aren’t checked yet.

A body that isn’t valid JSON gets a plain-text 400. If the database fails while the asset is being checked or after the file is stored, the server currently answers 200 with an empty body, so treat an empty body as an error. Storage failures get a plain-text 500, not the JSON shown.

id
required
string format: uuid

The asset’s id.

object
lang
required

The track’s language tag, such as en, en-US or fr-CA, or und when the language is unknown. Stored as sent and matched exactly.

string
label

A display name, such as English (US) or Forced. Leave it out for none; replacing a track without one clears the old label.

string
source_format
required

The format of content. idx is listed but not supported yet.

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

The subtitle file’s full text.

string

The stored track, already converted. Nothing is queued.

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

Malformed request

object
error
required

Human-readable error summary

string
Example
the request could not be completed

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

The format is idx, which isn’t supported yet. There’s no body.