BlogCore API

Video Link to SRT or VTT Subtitles: An API Recipe

Get timed segments from any video link, from captions or speech-to-text, and turn them into SRT or WebVTT in a few lines of Node or Python.

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.download only 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:

bash
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:

json
{
  "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:

javascript
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:

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:

output
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 trunks

Save 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.
  • maxCostDollars caps 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.

Keep reading

Put video and audio links to work in your app

One API for files, transcripts and metadata. Free to try, no card required.

Try free →