On this page7 sections
Video players, editors and clip tools want subtitles as a file: SRT for most editors and social uploads, WebVTT for the HTML <track> element. When your users paste a link instead of uploading a file, getting that file is the hard part:
- Official caption APIs are owner-only. YouTube's
captions.downloadonly works on videos the signed-in account can edit. For anyone else's video, it returns an error. - Many videos have no captions at all. TikTok, X, Instagram and podcast clips often don't, so a caption scraper has nothing to convert.
- It breaks on the server. Fetching captions or audio works from your laptop and gets blocked from AWS, Fly, a Vercel function or an agent sandbox.
The free route, if you already have the file
If your users upload files rather than paste links, you don't need an API for this. Run any speech-to-text library or service that outputs SRT or VTT on the file (most of them do), or pull an embedded subtitle track out of the container with your usual media tooling. The rest of this post is for the case where all you have is a link.
Step 1: get timed segments from the link
Importly returns the video's own captions when it has them and runs speech-to-text when it doesn't, with "mode": "auto". Either way you get the same timed segments:
curl -X POST https://api.importly.io/transcribe \
-H "Authorization: Bearer $IMPORTLY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://www.youtube.com/watch?v=jNQXAC9IVRw",
"mode": "auto",
"wait": true,
"maxCostDollars": 0.5
}'The finished transcript is in data.result, and data.result.data.segments is a list of { start, end, text } with times in seconds:
{
"segments": [
{ "start": 1.2, "end": 3.36, "text": "All right, so here we are, in front of the elephants" },
{ "start": 5.318, "end": 7.974, "text": "the cool thing about these guys is that they have really..." },
{ "start": 7.974, "end": 12.616, "text": "really really long trunks" }
]
}From captions you get one segment per caption line; from speech-to-text, one per sentence. Importly doesn't return SRT or VTT files itself, but segments in this shape take a few lines to convert. Long videos can outlast wait; then you get a jobId and collect the result from GET /transcribe/status or a webhook, as in the transcripts docs.
Step 2: write SRT or VTT
SRT numbers each cue and uses a comma before the milliseconds. WebVTT starts with a WEBVTT line and uses a dot. Node:
const stamp = (seconds, sep) => {
const ms = Math.round(seconds * 1000)
const h = String(Math.floor(ms / 3600000)).padStart(2, '0')
const m = String(Math.floor(ms / 60000) % 60).padStart(2, '0')
const s = String(Math.floor(ms / 1000) % 60).padStart(2, '0')
return `${h}:${m}:${s}${sep}${String(ms % 1000).padStart(3, '0')}`
}
const toSrt = (segments) =>
segments
.map((seg, i) => `${i + 1}\n${stamp(seg.start, ',')} --> ${stamp(seg.end, ',')}\n${seg.text.trim()}\n`)
.join('\n')
const toVtt = (segments) =>
'WEBVTT\n\n' +
segments.map((seg) => `${stamp(seg.start, '.')} --> ${stamp(seg.end, '.')}\n${seg.text.trim()}\n`).join('\n')Python:
def stamp(seconds, sep):
ms = round(seconds * 1000)
h, ms = divmod(ms, 3_600_000)
m, ms = divmod(ms, 60_000)
s, ms = divmod(ms, 1000)
return f"{h:02}:{m:02}:{s:02}{sep}{ms:03}"
def to_srt(segments):
return "\n".join(
f"{i}\n{stamp(seg['start'], ',')} --> {stamp(seg['end'], ',')}\n{seg['text'].strip()}\n"
for i, seg in enumerate(segments, 1)
)
def to_vtt(segments):
return "WEBVTT\n\n" + "\n".join(
f"{stamp(seg['start'], '.')} --> {stamp(seg['end'], '.')}\n{seg['text'].strip()}\n"
for seg in segments
)For the three segments above, toSrt gives:
1
00:00:01,200 --> 00:00:03,360
All right, so here we are, in front of the elephants
2
00:00:05,318 --> 00:00:07,974
the cool thing about these guys is that they have really...
3
00:00:07,974 --> 00:00:12,616
really really long trunksSave it as .srt, or serve the VTT version with Content-Type: text/vtt and point a <track kind="subtitles"> at it. Speech-to-text sentences can run long, so if your player shows them as big blocks, split a segment's text in two and divide its time range in proportion to the length of each half.
Subtitles and the video together
If your app also keeps the video, ask for both in one job with POST /import and "includeTranscript": true (add "transcriptProvider": "importly" for videos without captions). The same segments arrive in the result's transcript, next to the file. See import video from a URL.
What it costs
- From captions: $0.003 per video.
- Speech-to-text: $0.01 per minute of audio, fetching included, with a $0.01 minimum. A 10-minute video is $0.10.
maxCostDollarscaps a request, so a long video fails with a quote instead of running over.
It's free to try, no card required. See pricing.
Have your AI agent build it in
Connect https://mcp.importly.io/mcp to Claude Code, Cursor or another coding agent and ask it to add subtitle files to your app. It gets working code for your stack, writes the integration and tests real calls with your API key, and your backend uses the same key. The steps are in Have your agent build Importly into your app.
FAQ
Can I download SRT subtitles from any YouTube video with the official API?
No. captions.download in the YouTube Data API only works for videos owned by the account you authorize. For other videos you need captions fetched from the page, or speech-to-text on the audio.
Does Importly return SRT or VTT directly?
No. It returns timed segments in seconds, the same shape for captions and speech-to-text, and the conversion above turns them into either format.
What if the video has no captions?
With "mode": "auto", speech-to-text runs instead, at $0.01 a minute, and you get segments in the same shape.
Can I get subtitles in another language?
Pass language, such as es. For captions it picks that track if the video has one; for speech-to-text it sets the language to transcribe. It doesn't translate.
Related: Video transcription API, YouTube transcript API, X video transcript API.