# 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):

```sh
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

```sh
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:

```text
[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 <track> 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

```sh
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":

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

```json
{
  "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](https://vid2context.com/docs/contracts/http-api.md), 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](https://vid2context.com/index.md#try) 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](https://vid2context.com/docs/deploy/docker.md), [Cloudflare](https://vid2context.com/docs/deploy/cloudflare.md) 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](https://vid2context.com/docs/providers.md).