# Transcripts

All of these call `GET /api/v1/transcript` with different parameters. The CLI equivalent is `npx -y vid2context <url>` with the same flags, and agents use the MCP tool `get_transcript`.

## Plain text

**Get a transcript** (`GET /api/v1/transcript`)

```bash
curl -G https://vid2context.com/api/v1/transcript \
  --data-urlencode 'url=https://www.youtube.com/watch?v=jNQXAC9IVRw' \
  --data-urlencode format=text
```

Response recorded on 2026-11-14 (HTTP 200 OK):

```text
All right, so here we are, in front of the elephants the cool thing about these guys is that they have really... really really long trunks and that's cool (baaaaaaaaaaahhh!!) and that's pretty much all there is to say

```
## With timestamps

**Transcript with timestamps** (`GET /api/v1/transcript`)

```bash
curl -G https://vid2context.com/api/v1/transcript \
  --data-urlencode 'url=https://www.youtube.com/watch?v=jNQXAC9IVRw' \
  --data-urlencode format=text \
  --data-urlencode timestamps=1
```

Response recorded on 2026-11-14 (HTTP 200 OK):

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

```
## SRT captions

**Captions as SRT** (`GET /api/v1/transcript`)

```bash
curl -G https://vid2context.com/api/v1/transcript \
  --data-urlencode 'url=https://www.youtube.com/watch?v=jNQXAC9IVRw' \
  --data-urlencode format=srt
```

Response recorded on 2026-11-14 (HTTP 200 OK):

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

4
00:00:12,616 --> 00:00:14,367
and that's cool

5
00:00:14,421 --> 00:00:15,733
(baaaaaaaaaaahhh!!)

6
00:00:16,881 --> 00:00:18,881
and that's pretty much all there is to say

```
## WebVTT captions

**Captions as WebVTT** (`GET /api/v1/transcript`)

```bash
curl -G https://vid2context.com/api/v1/transcript \
  --data-urlencode 'url=https://www.youtube.com/watch?v=jNQXAC9IVRw' \
  --data-urlencode format=vtt
```

Response recorded on 2026-11-14 (HTTP 200 OK):

```text
WEBVTT

NOTE
Me at the zoo
Source: https://www.youtube.com/watch?v=jNQXAC9IVRw
Transcript: creator captions from youtube-captions

00:00:01.200 --> 00:00:03.360
All right, so here we are,
in front of the elephants

00:00:05.318 --> 00:00:07.974
the cool thing about these guys
is that they have really...

00:00:07.974 --> 00:00:12.616
really really long trunks

00:00:12.616 --> 00:00:14.367
and that's cool

00:00:14.421 --> 00:00:15.733
(baaaaaaaaaaahhh!!)

00:00:16.881 --> 00:00:18.881
and that's pretty much all there is to say

```
## Markdown

Title and metadata first, chapters as headings, and paragraphs that start with timestamp links.

**Markdown with chapter headings** (`GET /api/v1/transcript`)

```bash
curl -G https://vid2context.com/api/v1/transcript \
  --data-urlencode 'url=https://www.youtube.com/watch?v=jNQXAC9IVRw' \
  --data-urlencode format=markdown
```

Response recorded on 2026-11-14 (HTTP 200 OK):

```text
# Me at the zoo

- Channel: [jawed](https://www.youtube.com/channel/UC4QobU6STFB0P71PMvOGN5A)
- Published: 2005-04-23
- Duration: 0:19
- Source: https://www.youtube.com/watch?v=jNQXAC9IVRw
- Language: en
- Transcript: creator captions from youtube-captions

## Description

> Microplastics are accumulating in human brains at an alarming rate
> https://www.youtube.com/watch?v=0PT5c1z3LL8
>
> “Nanoplastics and Human Health” with Matthew J Campen, PhD, MSPH
> https://www.youtube.com/watch?v=RRBN_4L09Mg
>
> 00:00 Intro
> 00:05 The cool thing
> 00:17 End

## Intro (0:00)

[0:01](https://www.youtube.com/watch?v=jNQXAC9IVRw&t=1s) All right, so here we are, in front of the elephants

## The cool thing (0:05)

[0:05](https://www.youtube.com/watch?v=jNQXAC9IVRw&t=5s) the cool thing about these guys is that they have really... really really long trunks and that's cool (baaaaaaaaaaahhh!!) and that's pretty much all there is to say

```
## JSON

The full `VideoContext`: metadata, chapters, timed segments, and how the transcript was produced.

**The whole VideoContext as JSON** (`GET /api/v1/transcript`)

```bash
curl -G https://vid2context.com/api/v1/transcript \
  --data-urlencode 'url=https://www.youtube.com/watch?v=jNQXAC9IVRw' \
  --data-urlencode format=json
```

Response recorded on 2026-11-14 (HTTP 200 OK):

```json
{
  "metadata": {
    "ref": {
      "input": "https://www.youtube.com/watch?v=jNQXAC9IVRw",
      "platform": "youtube",
      "kind": "video",
      "id": "youtube:jNQXAC9IVRw",
      "nativeId": "jNQXAC9IVRw",
      "url": "https://www.youtube.com/watch?v=jNQXAC9IVRw"
    },
    "title": "Me at the zoo",
    "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,
    "publishedAt": "2005-04-23",
    "thumbnailUrl": "https://i.ytimg.com/vi/jNQXAC9IVRw/hqdefault.jpg?sqp=-oaymwEmCOADEOgC8quKqQMa8AEB-AG-AoAC8AGKAgwIABABGFUgWShlMA8=&rs=AOn4CLA9eLBatYv9WbkD4BbZ2Im-biSPTw",
    "tags": [
      "me at the zoo",
      "jawed karim",
      "first youtube video"
    ],
    "chapters": [
      {
        "title": "Intro",
        "startSec": 0,
        "endSec": 5
      },
      {
        "title": "The cool thing",
        "startSec": 5,
        "endSec": 17
      },
      {
        "title": "End",
        "startSec": 17,
        "endSec": 19
      }
    ],
    "isLive": false,
    "extra": {
      "viewCount": 448539222,
```

(92 more lines; run the request to see them.)
## Captions only

`mode=captions` never downloads audio. When a video has no captions it fails at once with `no-transcript`, which is what you want for a quick, cheap check. `mode=stt` does the opposite and always transcribes the audio.

**Captions only, never audio** (`GET /api/v1/transcript`): mode=captions fails fast with no-transcript instead of downloading audio for speech-to-text.

```bash
curl -G https://vid2context.com/api/v1/transcript \
  --data-urlencode 'url=https://www.youtube.com/watch?v=jNQXAC9IVRw' \
  --data-urlencode format=text \
  --data-urlencode timestamps=1 \
  --data-urlencode mode=captions
```

Response recorded on 2026-11-14 (HTTP 200 OK):

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

```
## Translate

`lang` with `translate=1` returns the transcript in that language. The platform's own track or translation is used when there is one; otherwise an LLM translates it on the free chain, keeping every segment and timestamp. `X-Translated-Via` says which happened. The stored transcript is never replaced.

**Translate a transcript** (`GET /api/v1/transcript`): X-Translated-Via says which step answered: source, platform or llm. The stored transcript stays in its own language.

```bash
curl -G https://vid2context.com/api/v1/transcript \
  --data-urlencode 'url=https://www.youtube.com/watch?v=jNQXAC9IVRw' \
  --data-urlencode format=text \
  --data-urlencode timestamps=1 \
  --data-urlencode lang=de \
  --data-urlencode translate=1
```

Response recorded on 2026-11-14 (HTTP 200 OK):

```text
[0:00] Also hier sind wir vor den Elefanten.
[0:05] Das Coole an den Typen ist dass sie sehr, sehr, sehr, lange Rüssel haben.
[0:12] Und das ist cool.
[0:17] Ansonsten gibt es nicht wirklich viel zu sagen.

```
## Remove sponsor segments

`skip` cuts SponsorBlock segments from a copy of the transcript: name the categories (`sponsor`, `selfpromo`, `intro`, `outro`, `interaction` and others), or send `skip=1` for the default set. This video's self-promotion and outro are gone from the response; compare the last timestamps with the [segments](https://vid2context.com/docs/examples/structure.md#sponsorblock-segments) that were removed.

**Remove sponsor and self-promotion segments** (`GET /api/v1/transcript`): SponsorBlock segments are cut from a copy; X-Data-Attribution credits the data.

```bash
curl -G https://vid2context.com/api/v1/transcript \
  --data-urlencode 'url=https://www.youtube.com/watch?v=MBRqu0YOH14' \
  --data-urlencode format=text \
  --data-urlencode timestamps=1 \
  --data-urlencode skip=selfpromo,outro
```

Response recorded on 2026-11-14 (HTTP 200 OK):

```text
[0:00] Human existence is scary and confusing.
[0:04] A few hundred thousand years ago, we became conscious and found ourselves in a strange place.
[0:09] It was filled with other beings. We could eat some; some could eat us.
[0:14] There was liquid stuff we could drink; things we could use to make more things.
[0:19] The daytime sky had a tiny yellow ball that warmed our skin.
[0:22] The night sky was filled with beautiful lights.
[0:25] This place was obviously made for us.
[0:28] Something was watching over us.
[0:29] We were home. This made everything much less scary and confusing.
[0:35] But the older we got, the more we learned about the world and ourselves.
[0:38] We learned that the twinkling lights are not shining beautifully for us, they just are.
[0:43] We learned that we're not at the center of what we now call the universe,
[0:46] and that it is much, much older than we thought.
[0:49] We learned that we're made of many little dead things,
[0:52] which make up bigger things that are not dead, for some reason,
[0:55] and that we're just another temporary stage in a history going back over a billion years.
[1:01] We learned, in awe, that we live on a moist speck of dust moving around a medium-sized star
[1:06] in a quiet region of one arm of an average galaxy, which is part of a galaxy group that we will never leave.
[1:11] And this group is only one of thousands that, together, make up a galaxy supercluster.
[1:16] But even our supercluster is only one in thousands that make up what we call the observable universe.
[1:22] The universe might be a million times bigger, but we will never know.
[1:27] We can throw words around like two hundred million galaxies
[1:30] or trillions of stars or bazillions of planets,
[1:33] but all of these numbers mean nothing. Our brains can't comprehend these concepts.
[1:38] The universe is too big. There is too much of it.
[1:42] But size is not the most troubling concept we have to deal with.
[1:45] It's time, or, more precisely, the time we have.
[1:49] If you're lucky enough to live to one hundred,
[1:51] you have five thousand two hundred weeks at your disposal.
[1:55] If you're twenty-five now, then you have three thousand nine hundred weeks left.
[1:59] If you're going to die at seventy, then there are two thousand three hundred and forty weeks left -
[2:05] a lot of time, but also ... not really.
[2:09] And then what?
[2:10] Your biological processes will break down,
[2:13] and the dynamic pattern that is you will stop beinge dynamic.
[2:17] It will dissolve until there is no you left.
[2:20] Some believe that there is a part of us we can't see or measure,
[2:23] but we have no way to find out, so this life might be it
[2:28] and we might end up dead forever.
[2:30] This is less scary than it sounds, though.
```

(53 more lines; run the request to see them.)
## The full context

`GET /api/v1/context` returns the same `VideoContext` as the JSON format, with an `ETag` for caching.

**The full context** (`GET /api/v1/context`): Metadata, timed segments, how the transcript was made, and every attempt.

```bash
curl -G https://vid2context.com/api/v1/context \
  --data-urlencode 'url=https://www.youtube.com/watch?v=jNQXAC9IVRw'
```

Response recorded on 2026-11-14 (HTTP 200 OK):

```json
{
  "metadata": {
    "ref": {
      "input": "https://www.youtube.com/watch?v=jNQXAC9IVRw",
      "platform": "youtube",
      "kind": "video",
      "id": "youtube:jNQXAC9IVRw",
      "nativeId": "jNQXAC9IVRw",
      "url": "https://www.youtube.com/watch?v=jNQXAC9IVRw"
    },
    "title": "Me at the zoo",
    "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,
    "publishedAt": "2005-04-23",
    "thumbnailUrl": "https://i.ytimg.com/vi/jNQXAC9IVRw/hqdefault.jpg?sqp=-oaymwEmCOADEOgC8quKqQMa8AEB-AG-AoAC8AGKAgwIABABGFUgWShlMA8=&rs=AOn4CLA9eLBatYv9WbkD4BbZ2Im-biSPTw",
    "tags": [
      "me at the zoo",
      "jawed karim",
      "first youtube video"
    ],
    "chapters": [
      {
        "title": "Intro",
        "startSec": 0,
        "endSec": 5
      },
      {
        "title": "The cool thing",
        "startSec": 5,
        "endSec": 17
      },
      {
        "title": "End",
        "startSec": 17,
        "endSec": 19
      }
    ],
    "isLive": false,
    "extra": {
      "viewCount": 448539222,
```

(92 more lines; run the request to see them.)
## Errors

**What an error looks like** (`GET /api/v1/transcript`): A video that does not exist.

```bash
curl -G https://vid2context.com/api/v1/transcript \
  --data-urlencode 'url=https://www.youtube.com/watch?v=xxxxxxxxxxx' \
  --data-urlencode format=text
```

Response recorded on 2026-11-14 (HTTP 404 Not Found):

```json
{
  "error": {
    "code": "not-found",
    "message": "YouTube xxxxxxxxxxx: ERROR (This video is unavailable)",
    "hint": "The video does not exist or was removed. Check the video id or URL."
  },
  "attempts": [
    {
      "id": "youtube",
      "stage": "resolve",
      "outcome": "ok",
      "detail": "youtube:xxxxxxxxxxx"
    },
    {
      "id": "youtube",
      "stage": "metadata",
      "outcome": "error",
      "reason": "not-found",
      "detail": "YouTube xxxxxxxxxxx: ERROR (This video is unavailable)"
    }
  ]
}
```
Every error has this shape. [Call the API from your code](https://vid2context.com/docs/tutorials/api-from-code.md) lists the codes and which ones to retry.
