Free YouTube transcript API#

vid2context includes an HTTP API that returns the transcript of a YouTube video (or any supported video) in text, Markdown, SRT, VTT, JSON or a context pack. It is free and open source, and it needs no YouTube API key. Run it on your own machine, where YouTube does not block the requests.

Run it#

From a clone of the repo (Node.js 22 or newer):

git clone https://github.com/nirholas/vid2context.git
cd vid2context
npm install
npm run start:server

The server listens on http://127.0.0.1:8787.

Get a transcript#

curl "http://127.0.0.1:8787/api/v1/transcript?url=https://www.youtube.com/watch?v=jNQXAC9IVRw&timestamps=1"

The response, as vid2context renders it from a recorded run:

[0:01] All right, so here we are, in front of the elephants
[0:05] the cool thing about these guys is that they have really...
[0:07] really really long trunks
[0:12] and that's cool
[0:14] (baaaaaaaaaaahhh!!)
[0:16] and that's pretty much all there is to say

format picks the formatter:

• text (.txt): Plain transcript text. With timestamps, one "[m:ss] line" per caption.
• json (.json): The full VideoContext as JSON: metadata, chapters, timed segments, and how it was produced.
• markdown (.md): Markdown transcript: title and metadata, chapters as headings, paragraphs prefixed with timestamp links. Options: linkTimestamps, includeComments, includeVisual.
• srt (.srt): SubRip (.srt) captions: at most 2 lines of 42 characters per cue, no overlaps, for players and editors.
• vtt (.vtt): WebVTT (.vtt) captions for the HTML element, with speaker voice tags when known.
• pack (.md): Context pack: one Markdown file for one or many videos, written for an AI model to read, with citation instructions. Options: maxTokens, includeComments, includeVisual, linkTimestamps.

Get everything as JSON#

curl "http://127.0.0.1:8787/api/v1/context?url=https://www.youtube.com/watch?v=jNQXAC9IVRw"

This returns the full VideoContext: metadata, chapters, timed segments and every attempt that was made. The metadata part for "Me at the zoo":

{
  "title": "Me at the zoo",
  "channel": "jawed",
  "description": "Microplastics are accumulating in human brains at an alarming rate\nhttps://www.youtube.com/watch?v=0PT5c1z3LL8\n\n“Nanoplastics and Human Health” with Matthew J Campen, PhD, MSPH\nhttps://www.youtube.com/watch?v=RRBN_4L09Mg\n\n00:00 Intro\n00:05 The cool thing\n00:17 End",
  "durationSec": 19,
  "chapters": [
    {
      "title": "Intro",
      "startSec": 0,
      "endSec": 5
    },
    {
      "title": "The cool thing",
      "startSec": 5,
      "endSec": 17
    },
    {
      "title": "End",
      "startSec": 17,
      "endSec": 19
    }
  ],
  "tags": [
    "me at the zoo",
    "jawed karim",
    "first youtube video"
  ]
}

Errors you can act on#

Every error has a stable code, a hint that says how to recover, and the attempts list:

{
  "error": { "code": "not-found", "message": "YouTube xxxxxxxxxxx: ERROR (This video is unavailable)", "hint": "Check the video id or URL; the video may have been removed." },
  "attempts": [{ "id": "youtube", "stage": "metadata", "outcome": "error", "reason": "not-found", "detail": "..." }]
}

That example is from the HTTP API contract, which lists every route, parameter and error code.

The hosted endpoint#

The same API answers on this site at https://vid2context.com/api/v1/, and the live demo on the home page calls it. YouTube often blocks requests from cloud servers, so treat the hosted endpoint as a demo and self-host for real use: on Docker, Cloudflare or your own machine.

Why it is free#

Captions cost nothing to fetch. When a video has no captions, speech-to-text runs free-first: local models, then free tiers with your key, then keyless hosts. Paid services run only when you set their key. See Providers and rungs.