Examples

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/api/v1/transcriptGet a transcript
BCP-47, for example en, de or pt-BR
auto (the default): captions first, then 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
Recorded response: 200 OK, 9 ms, 2026-11-14
content-type text/plain; charset=utf-8
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

GET/api/v1/transcriptTranscript with timestamps
BCP-47, for example en, de or pt-BR
auto (the default): captions first, then 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
Recorded response: 200 OK, 3 ms, 2026-11-14
content-type text/plain; charset=utf-8
[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

GET/api/v1/transcriptCaptions as SRT
BCP-47, for example en, de or pt-BR
auto (the default): captions first, then 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=srt
Recorded response: 200 OK, 2 ms, 2026-11-14
content-type application/x-subrip; charset=utf-8
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

GET/api/v1/transcriptCaptions as WebVTT
BCP-47, for example en, de or pt-BR
auto (the default): captions first, then 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=vtt
Recorded response: 200 OK, 2 ms, 2026-11-14
content-type text/vtt; charset=utf-8
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.

GET/api/v1/transcriptMarkdown with chapter headings
BCP-47, for example en, de or pt-BR
auto (the default): captions first, then 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=markdown
Recorded response: 200 OK, 2 ms, 2026-11-14
content-type text/markdown; charset=utf-8
# 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.

GET/api/v1/transcriptThe whole VideoContext as JSON
BCP-47, for example en, de or pt-BR
auto (the default): captions first, then 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=json
Recorded response: 200 OK, 2 ms, 2026-11-14
content-type application/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,
      "likeCount": 20138476,
      "dateText": "Apr 23, 2005",
      "channelHandle": "@jawed",
      "channelHandleUrl": "https://www.youtube.com/@jawed",
      "subscriberCountText": "6.74M subscribers",
      "isShort": false,
      "isLive": false,
      "isUpcoming": false,
      "isLiveContent": false,
      "ageRestricted": false,
      "membersOnly": false,
      "playability": "OK",
      "chapterSource": "description",
      "links": [
        "https://www.youtube.com/watch?v=0PT5c1z3LL8",
        "https://www.youtube.com/watch?v=RRBN_4L09Mg"
      ]
    },
    "channel": {
      "name": "jawed",
      "id": "UC4QobU6STFB0P71PMvOGN5A",
      "url": "https://www.youtube.com/channel/UC4QobU6STFB0P71PMvOGN5A"
    }
  },
  "transcript": {
    "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"
    },
    "language": "en",
    "origin": "creator-captions",
    "producer": "youtube-captions",
    "segments": [
      {
        "startSec": 1.2,
        "endSec": 3.36,

52 more lines not shown. Run it to see the whole response.

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.

GET/api/v1/transcriptCaptions only, never audio

mode=captions fails fast with no-transcript instead of downloading audio for speech-to-text.

auto (the default): captions first, then 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
Recorded response: 200 OK, 1.1 s, 2026-11-14
content-type text/plain; charset=utf-8
[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.

GET/api/v1/transcriptTranslate a transcript

X-Translated-Via says which step answered: source, platform or llm. The stored transcript stays in its own language.

BCP-47, for example en, de or pt-BR
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
Recorded response: 200 OK, 642 ms, 2026-11-14
content-type text/plain; charset=utf-8x-translated-via platform
[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 that were removed.

GET/api/v1/transcriptRemove sponsor and self-promotion segments

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
Recorded response: 200 OK, 1.4 s, 2026-11-14
content-type text/plain; charset=utf-8x-data-attribution Segment data: SponsorBlock (sponsor.ajay.app), CC BY-NC-SA 4.0
[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.
[2:33] If you don't remember the 13.75 billion years that went by before you existed,
[2:37] Then the trillions and trillions and trillions of years that come after will pass in no time once you're gone.
[2:43] Close your eyes. Count to 1.
[2:47] That's how long forever feels.
[2:49] And as far as we know, in the end, the universe itself will die and nothing will ever change again.
[2:56] Our videos induce existential dread in many people,
[2:59] and the last few minutes probably haven't helped.
[3:01] So, for once, we want to offer a different way of looking at these things:
[3:05] an unscientific, subjective point of view, the philosophy of Kurzgesagt, if you want.
[3:10] Please take it with a grain of salt; we don't know any more about human existence than you do.
[3:15] We counter existential dread with optimistic nihilism.
[3:19] What do we mean by that?
[3:21] Well, to summarize, it seems very unlikely that 200 trillion trillion stars have been made for us.
[3:28] In a way, it feels like the cruelest joke in existence has been played on us.
[3:31] We became self-aware only to realize this story is not about us.
[3:36] While it is great to know about electrons and the powerhouse of the cell,
[3:40] Science doesn't do a lot to make this less depressing.
[3:43] Okay, but so what?
[3:45] You only get one shot at life, which is scary, but it also sets you free.
[3:50] If the universe ends in heat death, every humiliation you suffer in your life will be forgotten.
[3:55] Every mistake you made will not matter in the end.
[3:58] Every bad thing you did will be voided.
[4:01] If our life is all we get to experience, then it's the only thing that matters.
[4:06] If the universe has no principles, the only principles relevant are the ones we decide on.
[4:11] If the universe has no purpose, then we get to dictate what its purpose is.
[4:16] Humans will most certainly cease to exist at some point,
[4:20] but before we do, we get to explore ourselves and the world around us.
[4:24] We get to experience feelings. We get to experience food, books, sunrises, and being with each other.
[4:30] The fact that we're even able to think about these things is already kind of incredible.
[4:35] It's easy to think of ourselves as separated from everything, but this is not true.
[4:40] We are as much the universe as a neutron star
[4:43] or a black hole or a nebula.
[4:45] Even better, actually, we are its thinking and feeling part:
[4:49] the centre organs of the universe.
[4:52] We are truly free in a universe-sized playground,
[4:55] so we might as well aim to be happy and to build some kind of utopia in the stars.
[5:00] It's not as if we've found out everything there is to know
[5:03] We don't know why the rules of the universe are as they are,
[5:06] how life came into existence, what life is.
[5:09] We have no idea what consciousness is or if we are alone in the universe.

13 more lines not shown. Run it to see the whole response.

The full context

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

GET/api/v1/contextThe full context

Metadata, timed segments, how the transcript was made, and every attempt.

BCP-47, for example en, de or pt-BR
auto (the default): captions first, then speech-to-text
bash
curl -G https://vid2context.com/api/v1/context \
  --data-urlencode 'url=https://www.youtube.com/watch?v=jNQXAC9IVRw'
Recorded response: 200 OK, 3 ms, 2026-11-14
content-type application/jsonetag "mKUNlClscAeErJQWgz-0oe4Jn1v"
{
  "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,
      "likeCount": 20138476,
      "dateText": "Apr 23, 2005",
      "channelHandle": "@jawed",
      "channelHandleUrl": "https://www.youtube.com/@jawed",
      "subscriberCountText": "6.74M subscribers",
      "isShort": false,
      "isLive": false,
      "isUpcoming": false,
      "isLiveContent": false,
      "ageRestricted": false,
      "membersOnly": false,
      "playability": "OK",
      "chapterSource": "description",
      "links": [
        "https://www.youtube.com/watch?v=0PT5c1z3LL8",
        "https://www.youtube.com/watch?v=RRBN_4L09Mg"
      ]
    },
    "channel": {
      "name": "jawed",
      "id": "UC4QobU6STFB0P71PMvOGN5A",
      "url": "https://www.youtube.com/channel/UC4QobU6STFB0P71PMvOGN5A"
    }
  },
  "transcript": {
    "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"
    },
    "language": "en",
    "origin": "creator-captions",
    "producer": "youtube-captions",
    "segments": [
      {
        "startSec": 1.2,
        "endSec": 3.36,

52 more lines not shown. Run it to see the whole response.

Errors

GET/api/v1/transcriptWhat an error looks like

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
Recorded response: 404 Not Found, 68 ms, 2026-11-14
content-type application/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 lists the codes and which ones to retry.

Where examples run

Any vid2context server: your own deployment, or one started from a clone of the repo with VID2CONTEXT_CORS_ORIGINS=this origin npm run start:server (it listens on http://127.0.0.1:8787). The CORS variable lets this page read its responses.

Only for servers that set VID2CONTEXT_API_KEYS. Sent as Authorization: Bearer, kept in this tab's session storage, and never written into the snippets (they read $VID2CONTEXT_API_KEY).