A video captions API that transcribes speech into subtitles

What the captions API does

When you ask for captions, the audio of a finished video is transcribed into subtitles. You get WebVTT (the format browsers' <track> elements and most players use), SRT, and a plain-text transcript. For streaming videos the HLS stream also gets a subtitle track, so standard players show a CC button without any extra work. Captions are produced only when you request them.

Example

Add "captions": true to complete, an import, an edit or a reprocess:

POST /videos/3f1c…/complete
{ "captions": true }

GET /videos/3f1c… (once ready)
"captions": { "status": "ready", "language": "en",
              "vttUrl": "https://…/en.vtt?…", "srtUrl": "https://…/en.srt?…", "txtUrl": "https://…/en.txt?…" }

The language is detected automatically. To set it, send {"language": "es"} with an ISO 639-1 code such as en, es, fr, de, ja or zh.

Built so it can't hurt your video

• The video doesn't wait. It is published and playable first; captions follow, typically a few minutes later. Until then captions.status is processing, so keep polling or wait for the video.ready webhook, which carries the captions object.
• It never fails your video. If captions can't be made the status is failed and the video is unaffected. Over the limits below it is skipped with a reason.
• No repeat charges. A reprocess with the same trim reuses the earlier transcript instead of transcribing again.

Using the files

In your own player, add the WebVTT link as a subtitle track; the crossorigin attribute on the video lets the browser load it:

<track kind="subtitles" src="…vttUrl…" srclang="en" default>

HLS players pick up the stream's own subtitle track without this. The <video-piper> web component takes a captions attribute for the MP4 and a cc attribute to show captions from the start; its links come from your own endpoint, as in the documentation's server example. Caption links last 15 minutes, like downloads, so fetch the status again when you need fresh ones.

Captions work with the browser components too: an upload token can set "captions": true, so recordings made on your site are captioned without the page being able to change it.

Cost and limits

Which plans include captions

Captions (speech to text) are a Pro and Scale feature. Each captioned minute adds 2 processing minutes to your usage, only when a transcript is actually made.

Usage beyond a paid plan is billed at $0.09 per processing minute, $0.15 per GB-month of storage and $0.55 per GB of delivery. Full details are on the pricing page.

In the documentation

• Captions (Pro and Scale)
• Processing options
• Webhooks (video.ready carries captions)
• Upload tokens (captions on recorder uploads)
• Limits

Frequently asked questions