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 withWEBVTT(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.ssaandass: only theDialoguelines 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.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The asset’s id.
Request Body required
Section titled “Request Body required ”object
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.
A display name, such as English (US) or Forced. Leave it out for none; replacing a track without one clears the old label.
The format of content. idx is listed but not supported yet.
The subtitle file’s full text.
Responses
Section titled “ Responses ”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
The track’s language tag, such as en or fr-CA. und means the
language couldn’t be worked out from the file name.
A display name, such as English (US) or Forced. Empty when none
was given.
The SHA-256 of the stored WebVTT file.
The format the track was uploaded in. It’s stored as WebVTT whatever the source format.
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.
Malformed request
object
Human-readable error summary
Example
the request could not be completedAuthentication required, missing, or invalid
object
Human-readable error summary
Example
the request could not be completedExample
{ "error": "authentication required: sign in and retry with a valid session or API token"}Resource not found
object
Human-readable error summary
Example
the request could not be completedRequest shape is valid but the action doesn’t apply (e.g. subtitles on a non-video/audio asset).
object
Human-readable error summary
Example
the request could not be completedThe format is idx, which isn’t supported yet. There’s no body.