Tutorials

Your first transcript

This tutorial takes one short video, "Me at the zoo" (19 seconds, the first video on YouTube), from a URL to a transcript an AI model can cite. Every step is a request you can run here.

1. Check the server

Start by asking the server what it is. /health needs no video and returns the version, the runtime, the output formats, and every provider and model rung with whether it can run.

GET/api/v1/healthCheck the server

Version, runtime, formats, and every provider and rung with whether it is enabled.

bash
curl https://vid2context.com/api/v1/health
Recorded response: 200 OK, 6 ms, 2026-11-14
content-type application/json
{
  "ok": true,
  "name": "vid2context",
  "version": "0.1.0",
  "runtime": "node",
  "formats": [
    {
      "id": "text",
      "description": "Plain transcript text. With timestamps, one \"[m:ss] line\" per caption.",
      "mimeType": "text/plain; charset=utf-8"
    },
    {
      "id": "json",
      "description": "The full VideoContext as JSON: metadata, chapters, timed segments, and how it was produced.",
      "mimeType": "application/json"
    },
    {
      "id": "markdown",
      "description": "Markdown transcript: title and metadata, chapters as headings, paragraphs prefixed with timestamp links. Options: linkTimestamps, includeComments, includeVisual.",
      "mimeType": "text/markdown; charset=utf-8"
    },
    {
      "id": "srt",
      "description": "SubRip (.srt) captions: at most 2 lines of 42 characters per cue, no overlaps, for players and editors.",
      "mimeType": "application/x-subrip; charset=utf-8"
    },
    {
      "id": "vtt",
      "description": "WebVTT (.vtt) captions for the HTML <track> element, with speaker voice tags when known.",
      "mimeType": "text/vtt; charset=utf-8"
    },
    {
      "id": "pack",
      "description": "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.",
      "mimeType": "text/markdown; charset=utf-8"
    }
  ],
  "providers": [
    {
      "id": "bilibili",
      "kind": "source",
      "name": "Bilibili",
      "enabled": true
    },
    {
      "id": "bilibili-captions",
      "kind": "captions",
      "name": "Bilibili subtitles",
      "enabled": true
    },
    {
      "id": "cloudflare-ai-stt",
      "kind": "stt",
      "name": "Cloudflare Workers AI speech-to-text",
      "rungs": [
        {
          "id": "stt/cloudflare-binding/@cf/openai/whisper-large-v3-turbo",
          "service": "cloudflare-binding",
          "model": "@cf/openai/whisper-large-v3-turbo",
          "tier": "free",
          "enabled": false,
          "requires": [
            "CLOUDFLARE_AI_BINDING"
          ]
        },
        {
          "id": "stt/cloudflare-binding/@cf/openai/whisper",
          "service": "cloudflare-binding",
          "model": "@cf/openai/whisper",
          "tier": "free",
          "enabled": false,
          "requires": [
            "CLOUDFLARE_AI_BINDING"
          ]
        },
        {
          "id": "stt/cloudflare/@cf/openai/whisper-large-v3-turbo",
          "service": "cloudflare",
          "model": "@cf/openai/whisper-large-v3-turbo",
          "tier": "free",

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

2. Get the transcript

One request with the video URL returns the transcript as plain text. Any input a source understands works in url: a full YouTube link, a short youtu.be link, or the bare id jNQXAC9IVRw.

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

The first request for a video does the work: it reads the platform's captions (or, when there are none, downloads the audio and runs speech-to-text) and saves the result in the server's library. Later requests for the same video answer from the library, which is why the recorded time can be a few milliseconds.

3. Add timestamps

Agents cite moments, so they need times. timestamps=1 prefixes each caption line with [m:ss].

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

4. Captions files

The same transcript renders in every format the server has. SRT and WebVTT are captions files for players and editors: at most two lines of 42 characters per cue, and no overlaps.

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

Change Format to markdown, json or vtt and run it again; the snippets follow. The list comes from the server's formatter map, so GET /api/v1/formats always has the current one.

5. See how it was made

/context returns the whole VideoContext as JSON: the metadata and chapters, the timed segments, and two fields that matter when you build on it:

  • transcript.origin says how much to trust the text: creator-captions, auto-captions, native-transcript, stt or video-model.
  • attempts lists every provider and rung that was tried, in order, with the outcome and, for failures, the reason.
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.

The response carries an ETag. Send it back as If-None-Match and an unchanged context answers 304 with no body.

When something fails

Errors have one shape on every route: a stable code, a message, a hint that says how to recover, and the same attempts list.

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)"
    }
  ]
}

Next

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).