# Video structure

These requests read the parts of a video around the transcript, or one piece of it.

## Metadata only

Title, channel, duration, chapters and tags, without fetching captions or audio.

**Metadata only** (`GET /api/v1/metadata`): Title, channel, duration and chapters, without fetching captions or audio.

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

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

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

(23 more lines; run the request to see them.)
## Outline

Chapters with start times, timestamp links and token counts, so an agent can pick what to read.

**Outline with token counts** (`GET /api/v1/outline`)

```bash
curl -G https://vid2context.com/api/v1/outline \
  --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,
```

(46 more lines; run the request to see them.)
## Outline of a video without chapters

**Outline of a video without chapters** (`GET /api/v1/outline`): No chapters, so the outline is sections of about five minutes, cut where the speech pauses.

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

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

```json
{
  "metadata": {
    "ref": {
      "input": "https://www.youtube.com/watch?v=MBRqu0YOH14",
      "platform": "youtube",
      "kind": "video",
      "id": "youtube:MBRqu0YOH14",
      "nativeId": "MBRqu0YOH14",
      "url": "https://www.youtube.com/watch?v=MBRqu0YOH14"
    },
    "title": "Optimistic Nihilism",
    "description": "The philosophy of Kurzgesagt.\n\n\nOUR CHANNELS\n▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀\nGerman Channel: https://kgs.link/youtubeDE \nSpanish Channel: https://kgs.link/youtubeES \n\n\nHOW CAN YOU SUPPORT US?\n▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀\nThis is how we make our living and it would be a pleasure if you support us!\n\nGet Merch designed with ❤ from https://kgs.link/shop  \nJoin the Patreon Bird Army 🐧 https://kgs.link/patreon  \n\n\nDISCUSSIONS & SOCIAL MEDIA\n▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀\nReddit:            https://kgs.link/reddit\nInstagram:     https://kgs.link/instagram\nTwitter:           https://kgs.link/twitter\nFacebook:      https://kgs.link/facebook\nDiscord:          https://kgs.link/discord\nNewsletter:    https://kgs.link/newsletter\n\n\nOUR VOICE\n▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀\nThe Kurzgesagt voice is from \nSteve Taylor:  https://kgs.link/youtube-voice\n\n\nOUR MUSIC ♬♪\n▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀\n700+ minutes of Kurzgesagt Soundtracks by Epic Mountain:\n\nSpotify:            https://kgs.link/music-spotify\nSoundcloud:   https://kgs.link/music-soundcloud\nBandcamp:     https://kgs.link/music-bandcamp\nYoutube:          https://kgs.link/music-youtube\nFacebook:       https://kgs.link/music-facebook\n\nThe Soundtrack of this video:\nSoundcloud: http://bit.ly/2vZRSnI\nBandcamp: http://bit.ly/2tYuKUY\nFacebook: http://bit.ly/2qW6bY4\n\n\nHelp us caption & translate this video!\n\nhttp://www.youtube.com/timedtext_cs_panel?c=UCsXVk37bltHxD1rDPwtNM8Q&tab=2\n\nOptimistic Nihilism",
    "durationSec": 446,
    "publishedAt": "2017-07-26",
    "thumbnailUrl": "https://i.ytimg.com/vi/MBRqu0YOH14/maxresdefault.jpg",
    "language": "en",
    "tags": [
      "optimism",
      "existence",
      "existential",
      "meaning of life",
      "purpose",
      "existentialism",
      "atheism",
      "philosophy",
      "nihilism"
    ],
    "chapters": [],
    "isLive": false,
    "extra": {
      "viewCount": 18903134,
      "likeCount": 982145,
      "dateText": "Jul 26, 2017",
      "channelHandle": "@kurzgesagt",
      "channelHandleUrl": "https://www.youtube.com/@kurzgesagt",
      "subscriberCountText": "25.8M subscribers",
      "isShort": false,
      "isLive": false,
      "isUpcoming": false,
      "isLiveContent": false,
```

(42 more lines; run the request to see them.)
## One chapter

**One chapter** (`GET /api/v1/section`)

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

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

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

```
## A time range

**A time range** (`GET /api/v1/section`): from and to take seconds, m:ss or h:mm:ss. to is exclusive.

```bash
curl -G https://vid2context.com/api/v1/section \
  --data-urlencode 'url=https://www.youtube.com/watch?v=cCPsdFdlshc' \
  --data-urlencode from=5:00 \
  --data-urlencode to=6:00 \
  --data-urlencode format=text \
  --data-urlencode timestamps=1
```

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

```text
[4:58] They're robust, reliable.
[5:00] They work really well.
[5:01] They just drink a little oil.
[5:02] They drink a little oil.
[5:03] As they age, one thing you will note on these trucks is they will drink some oil.
[5:06] Well, this one's got 131,000 miles on it, and it drinks a quart and a half between oil changes.
[5:11] You know what, though?
[5:12] Not that bad.
[5:13] My 2018 Audi Q7 drank about a quart between oil changes, which is normal.
[5:18] Blake, you have an Audi.
[5:19] You know this drill.
[5:20] Blake, who's filming this.
[5:22] And it happens.
[5:23] Yeah.
[5:24] You know, I'm not making excuses for anyone.
[5:25] You just got to just say, hey, I want a G55.
[5:28] I'll preface, that's on a 5,000-mile service interval, too.
[5:31] Yeah.
[5:31] So, they're pretty easy to maintain.
[5:32] So, still uses the 113 motor, super reliable.
[5:36] So, this generation was available with the M113 up until through 2012.
[5:41] Yes.
[5:42] So, you have two options, G500 or the G55 AMG.
[5:45] Let's take a look inside.
[5:46] Yep.
[5:47] So, come around here, Blake.
[5:48] Hop in.
[5:48] I want to touch on a couple things here.
[5:50] So, the big thing on these trucks, and this is an MBUSA truck, is the first thing you're
[5:55] going to notice is the door panel.
[5:57] It is physically wider.
[5:58] We've now got our door switches and our seat switches on the door.

```
## Top comments

The source's own comment order, with likes, the pinned flag and replies. Raise `limit` for more (up to 1000).

**Top comments** (`GET /api/v1/comments`)

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

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

```json
{
  "comments": [
    {
      "id": "UgzuC3zzpRZkjc5Qzsd4AaABAg",
      "author": "@SanDiegoZoo",
      "text": "We're so honored that the first ever YouTube video was filmed here!",
      "likes": 4800000,
      "publishedAt": "2020-11-15",
      "isPinned": true,
      "replies": [
        {
          "id": "UgzuC3zzpRZkjc5Qzsd4AaABAg.958xaQsh63D958yN1-HDaK",
          "author": "@TheGreekPianist",
          "text": "San Diego Zoo That’s so awesome! I’m so glad the first YouTube video featured cute animals in it! 😊🐘",
          "likes": 206000,
          "publishedAt": "2020-11-15"
        },
        {
          "id": "UgzuC3zzpRZkjc5Qzsd4AaABAg.958xaQsh63D959Rh74Nkgr",
          "author": "@twitchgraal9030",
          "text": "Very cool!",
          "likes": 71000,
          "publishedAt": "2020-11-15"
        },
        {
          "id": "UgzuC3zzpRZkjc5Qzsd4AaABAg.958xaQsh63D959STS_MHCY",
          "author": "@simboca",
          "text": "cool",
          "likes": 57000,
          "publishedAt": "2020-11-15"
        },
        {
          "id": "UgzuC3zzpRZkjc5Qzsd4AaABAg.958xaQsh63D959eJMn2Pcr",
          "author": "@newyork5532",
          "text": ".",
          "likes": 54000,
          "publishedAt": "2020-11-15"
        },
        {
          "id": "UgzuC3zzpRZkjc5Qzsd4AaABAg.958xaQsh63D95AEkVnh_di",
```

(9 more lines; run the request to see them.)
## Caption languages

**Caption languages** (`GET /api/v1/caption-languages`): Caption tracks (creator or auto) and the languages YouTube can translate into.

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

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

```json
{
  "videoId": "youtube:jNQXAC9IVRw",
  "url": "https://www.youtube.com/watch?v=jNQXAC9IVRw",
  "tracks": [
    {
      "language": "en",
      "name": "English",
      "origin": "creator-captions",
      "translatable": true,
      "provider": "youtube-captions"
    },
    {
      "language": "de",
      "name": "German",
      "origin": "creator-captions",
      "translatable": true,
      "provider": "youtube-captions"
    },
    {
      "language": "en",
      "name": "English",
      "origin": "creator-captions",
      "provider": "ytdlp-captions"
    },
    {
      "language": "de",
      "name": "German",
      "origin": "creator-captions",
      "provider": "ytdlp-captions"
    },
    {
      "language": "en",
      "name": "en",
      "origin": "auto-captions",
      "provider": "ytdlp-captions"
    },
    {
      "language": "de",
      "name": "de",
      "origin": "auto-captions",
```

(8 more lines; run the request to see them.)
## SponsorBlock segments

Sponsor reads, self-promotion, intros, outros and reminders, with their times and the share of the transcript each covers. Segment data comes from SponsorBlock under CC BY-NC-SA 4.0, and the response says so.

**SponsorBlock segments** (`GET /api/v1/skips`)

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

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

```json
{
  "videoId": "youtube:MBRqu0YOH14",
  "source": "sponsorblock",
  "attribution": "Segment data: SponsorBlock (sponsor.ajay.app), CC BY-NC-SA 4.0",
  "segments": [
    {
      "category": "selfpromo",
      "startSec": 352.286,
      "endSec": 431.234,
      "votes": 0,
      "uuid": "b028b54b3a74297a9d1b3a7bfd1ac05651c0a843140800fb321299bd55d26a337",
      "actionType": "skip",
      "time": "5:52-7:11",
      "durationSec": 78.948,
      "url": "https://www.youtube.com/watch?v=MBRqu0YOH14&t=352s",
      "transcript": {
        "lines": 0,
        "share": 0,
        "preview": ""
      }
    },
    {
      "category": "outro",
      "startSec": 431.234,
      "endSec": 445.721,
      "votes": 0,
      "uuid": "046c26921855cbb5e3c655001554462bae5d982621f2dff74ab8bb474db0da1e7",
      "actionType": "skip",
      "time": "7:11-7:25",
      "durationSec": 14.487,
      "url": "https://www.youtube.com/watch?v=MBRqu0YOH14&t=431s",
      "transcript": {
        "lines": 0,
        "share": 0,
        "preview": ""
      }
    }
  ],
  "coveredSec": 93.435,
  "coveredShare": 0.209,
```

(2 more lines; run the request to see them.)
## Generate chapters

An LLM on the free chain proposes chapters from the transcript. A video that already has chapters answers `bad-request` unless you send `force: true`, as this example does, so you can compare the proposal with the creator's chapters. Untick **Force** to see that error.

**Generate chapters** (`POST /api/v1/chapters`): An LLM on the free chain proposes chapters from the transcript. This video has six of its own; force asks for new ones to compare.

```bash
curl https://vid2context.com/api/v1/chapters \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://www.youtube.com/watch?v=PzJL3aBRas8",
  "force": true
}'
```

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

```json
{
  "videoId": "youtube:PzJL3aBRas8",
  "chapters": [
    {
      "title": "Finding and building the dream 2015 G-Wagon",
      "startSec": 0,
      "endSec": 316.96000000000004
    },
    {
      "title": "Why I'm selling for a Ford F-150 Raptor",
      "startSec": 316.96000000000004,
      "endSec": 697
    }
  ],
  "producer": "llm/kilo/nvidia/nemotron-3-ultra-550b-a55b:free",
  "rung": "llm/kilo/nvidia/nemotron-3-ultra-550b-a55b:free",
  "model": "nvidia/nemotron-3-ultra-550b-a55b:free",
  "source": "auto",
  "method": "texttiling+llm",
  "durationSec": 697,
  "notes": [
    "Kept the start of chapter 2 at 317 s: the model moved it to 369.84 s, outside its window."
  ],
  "attempts": [
    {
      "id": "llm/cloudflare/@cf/meta/llama-3.3-70b-instruct-fp8-fast",
      "stage": "llm",
      "outcome": "error",
      "reason": "auth-401",
      "detail": "cloudflare chat: HTTP 401 {\"result\":null,\"success\":false,\"errors\":[{\"code\":10000,\"message\":\"Authentication error\"}],\"messages\":[]}",
      "ms": 73
    },
    {
      "id": "llm/kilo/nvidia/nemotron-3-ultra-550b-a55b:free",
      "stage": "llm",
      "outcome": "ok",
      "ms": 1766
    }
  ]
}
```
## Key moments

**Key moments** (`GET /api/v1/key-moments`): Chosen by the LLM chain; every timestamp is checked against real segments.

```bash
curl -G https://vid2context.com/api/v1/key-moments \
  --data-urlencode 'url=https://www.youtube.com/watch?v=cCPsdFdlshc' \
  --data-urlencode count=5
```

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

```json
{
  "videoId": "youtube:cCPsdFdlshc",
  "title": "Best & Worst G-Wagon Years: Reliability, Interiors & Engines Ranked!",
  "url": "https://www.youtube.com/watch?v=cCPsdFdlshc",
  "moments": [
    {
      "startSec": 69.5,
      "timestamp": "[1:09]",
      "title": "M113 V8 Engine Praised",
      "why": "The 2000 G500's M113 V8 is highlighted as a legendary, ultra-reliable 'Land Cruiser Killer' with simple design, cheap parts, and global availability.",
      "url": "https://www.youtube.com/watch?v=cCPsdFdlshc&t=69s"
    },
    {
      "startSec": 276.11999999999995,
      "timestamp": "[4:36]",
      "title": "G55 AMG Supercharged Era",
      "why": "Explains the shift from naturally aspirated to the 491-hp supercharged 'Kompressor' V8 in 2005, defining the performance character of the G55 through 2012.",
      "url": "https://www.youtube.com/watch?v=cCPsdFdlshc&t=276s"
    },
    {
      "startSec": 577.34,
      "timestamp": "[9:37]",
      "title": "M278 V8 & 7-Speed Debut",
      "why": "Introduces the 2013-2015 G550's naturally aspirated M278 V8 and 7-speed transmission, called a major technological leap and the last of the NA V8s.",
      "url": "https://www.youtube.com/watch?v=cCPsdFdlshc&t=577s"
    },
    {
      "startSec": 919.1,
      "timestamp": "[15:19]",
      "title": "Off-Road Sweet Spot Identified",
      "why": "Reveals the 2013-2015 NA V8 is preferred for off-roading due to lack of auxiliary coolers, allowing better bumper fitment and less throttle twitchiness than turbo models.",
      "url": "https://www.youtube.com/watch?v=cCPsdFdlshc&t=919s"
    },
    {
      "startSec": 1014.06,
      "timestamp": "[16:54]",
      "title": "Final Buying Verdicts",
      "why": "Summarizes target buyers: early G500 for value/entry, G55 for power/fun, 2013-15 G550 for ultimate daily/off-road balance, and pre-2002 for investment/collectibility.",
      "url": "https://www.youtube.com/watch?v=cCPsdFdlshc&t=1014s"
    }
```

(29 more lines; run the request to see them.)