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

**Check the server** (`GET /api/v1/health`): Version, runtime, formats, and every provider and rung with whether it is enabled.

```bash
curl https://vid2context.com/api/v1/health
```

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

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

(881 more lines; run the request to see them.)
## 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 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

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

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

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

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

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

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

**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)"
    }
  ]
}
```
## Next

- [Read a long video by chapter](https://vid2context.com/docs/tutorials/long-videos.md), without sending the whole transcript to a model.
- [All transcript requests](https://vid2context.com/docs/examples/transcripts.md): languages, translation, sponsor removal and captions-only mode.
