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.
/api/v1/healthCheck the serverVersion, runtime, formats, and every provider and rung with whether it is enabled.
curl https://vid2context.com/api/v1/healthconst BASE = 'https://vid2context.com';
const res = await fetch(`${BASE}/api/v1/health`);
if (!res.ok) {
const { error } = await res.json();
throw new Error(`${error.code}: ${error.message} ${error.hint ?? ''}`);
}
console.log(JSON.stringify(await res.json(), null, 2));import json
import urllib.error
import urllib.request
BASE = "https://vid2context.com"
headers = {}
req = urllib.request.Request(f"{BASE}/api/v1/health", headers=headers)
try:
with urllib.request.urlopen(req, timeout=300) as res:
print(json.dumps(json.load(res), indent=2))
except urllib.error.HTTPError as err:
error = json.load(err)["error"]
raise SystemExit(f"{error['code']}: {error['message']} {error.get('hint', '')}"){
"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.
/api/v1/transcriptGet a transcriptcurl -G https://vid2context.com/api/v1/transcript \
--data-urlencode 'url=https://www.youtube.com/watch?v=jNQXAC9IVRw' \
--data-urlencode format=textconst BASE = 'https://vid2context.com';
const params = new URLSearchParams({
url: 'https://www.youtube.com/watch?v=jNQXAC9IVRw',
format: 'text',
});
const res = await fetch(`${BASE}/api/v1/transcript?${params}`);
if (!res.ok) {
const { error } = await res.json();
throw new Error(`${error.code}: ${error.message} ${error.hint ?? ''}`);
}
console.log(await res.text());import json
import urllib.error
import urllib.parse
import urllib.request
BASE = "https://vid2context.com"
params = urllib.parse.urlencode({
"url": "https://www.youtube.com/watch?v=jNQXAC9IVRw",
"format": "text",
})
headers = {}
req = urllib.request.Request(f"{BASE}/api/v1/transcript?{params}", headers=headers)
try:
with urllib.request.urlopen(req, timeout=300) as res:
print(res.read().decode())
except urllib.error.HTTPError as err:
error = json.load(err)["error"]
raise SystemExit(f"{error['code']}: {error['message']} {error.get('hint', '')}")npx -y vid2context get 'https://www.youtube.com/watch?v=jNQXAC9IVRw' --format text{
"name": "get_transcript",
"arguments": {
"url": "https://www.youtube.com/watch?v=jNQXAC9IVRw",
"format": "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].
/api/v1/transcriptTranscript with timestampscurl -G https://vid2context.com/api/v1/transcript \
--data-urlencode 'url=https://www.youtube.com/watch?v=jNQXAC9IVRw' \
--data-urlencode format=text \
--data-urlencode timestamps=1const BASE = 'https://vid2context.com';
const params = new URLSearchParams({
url: 'https://www.youtube.com/watch?v=jNQXAC9IVRw',
format: 'text',
timestamps: '1',
});
const res = await fetch(`${BASE}/api/v1/transcript?${params}`);
if (!res.ok) {
const { error } = await res.json();
throw new Error(`${error.code}: ${error.message} ${error.hint ?? ''}`);
}
console.log(await res.text());import json
import urllib.error
import urllib.parse
import urllib.request
BASE = "https://vid2context.com"
params = urllib.parse.urlencode({
"url": "https://www.youtube.com/watch?v=jNQXAC9IVRw",
"format": "text",
"timestamps": "1",
})
headers = {}
req = urllib.request.Request(f"{BASE}/api/v1/transcript?{params}", headers=headers)
try:
with urllib.request.urlopen(req, timeout=300) as res:
print(res.read().decode())
except urllib.error.HTTPError as err:
error = json.load(err)["error"]
raise SystemExit(f"{error['code']}: {error['message']} {error.get('hint', '')}")npx -y vid2context get 'https://www.youtube.com/watch?v=jNQXAC9IVRw' --format text --timestamps{
"name": "get_transcript",
"arguments": {
"url": "https://www.youtube.com/watch?v=jNQXAC9IVRw",
"format": "text",
"timestamps": true
}
}[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.
/api/v1/transcriptCaptions as SRTcurl -G https://vid2context.com/api/v1/transcript \
--data-urlencode 'url=https://www.youtube.com/watch?v=jNQXAC9IVRw' \
--data-urlencode format=srtconst BASE = 'https://vid2context.com';
const params = new URLSearchParams({
url: 'https://www.youtube.com/watch?v=jNQXAC9IVRw',
format: 'srt',
});
const res = await fetch(`${BASE}/api/v1/transcript?${params}`);
if (!res.ok) {
const { error } = await res.json();
throw new Error(`${error.code}: ${error.message} ${error.hint ?? ''}`);
}
console.log(await res.text());import json
import urllib.error
import urllib.parse
import urllib.request
BASE = "https://vid2context.com"
params = urllib.parse.urlencode({
"url": "https://www.youtube.com/watch?v=jNQXAC9IVRw",
"format": "srt",
})
headers = {}
req = urllib.request.Request(f"{BASE}/api/v1/transcript?{params}", headers=headers)
try:
with urllib.request.urlopen(req, timeout=300) as res:
print(res.read().decode())
except urllib.error.HTTPError as err:
error = json.load(err)["error"]
raise SystemExit(f"{error['code']}: {error['message']} {error.get('hint', '')}")npx -y vid2context get 'https://www.youtube.com/watch?v=jNQXAC9IVRw' --format srt{
"name": "get_transcript",
"arguments": {
"url": "https://www.youtube.com/watch?v=jNQXAC9IVRw",
"format": "srt"
}
}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.originsays how much to trust the text:creator-captions,auto-captions,native-transcript,sttorvideo-model.attemptslists every provider and rung that was tried, in order, with the outcome and, for failures, the reason.
/api/v1/contextThe full contextMetadata, timed segments, how the transcript was made, and every attempt.
curl -G https://vid2context.com/api/v1/context \
--data-urlencode 'url=https://www.youtube.com/watch?v=jNQXAC9IVRw'const BASE = 'https://vid2context.com';
const params = new URLSearchParams({
url: 'https://www.youtube.com/watch?v=jNQXAC9IVRw',
});
const res = await fetch(`${BASE}/api/v1/context?${params}`);
if (!res.ok) {
const { error } = await res.json();
throw new Error(`${error.code}: ${error.message} ${error.hint ?? ''}`);
}
console.log(JSON.stringify(await res.json(), null, 2));import json
import urllib.error
import urllib.parse
import urllib.request
BASE = "https://vid2context.com"
params = urllib.parse.urlencode({
"url": "https://www.youtube.com/watch?v=jNQXAC9IVRw",
})
headers = {}
req = urllib.request.Request(f"{BASE}/api/v1/context?{params}", headers=headers)
try:
with urllib.request.urlopen(req, timeout=300) as res:
print(json.dumps(json.load(res), indent=2))
except urllib.error.HTTPError as err:
error = json.load(err)["error"]
raise SystemExit(f"{error['code']}: {error['message']} {error.get('hint', '')}"){
"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.
/api/v1/transcriptWhat an error looks likeA video that does not exist.
curl -G https://vid2context.com/api/v1/transcript \
--data-urlencode 'url=https://www.youtube.com/watch?v=xxxxxxxxxxx' \
--data-urlencode format=textconst BASE = 'https://vid2context.com';
const params = new URLSearchParams({
url: 'https://www.youtube.com/watch?v=xxxxxxxxxxx',
format: 'text',
});
const res = await fetch(`${BASE}/api/v1/transcript?${params}`);
if (!res.ok) {
const { error } = await res.json();
throw new Error(`${error.code}: ${error.message} ${error.hint ?? ''}`);
}
console.log(await res.text());import json
import urllib.error
import urllib.parse
import urllib.request
BASE = "https://vid2context.com"
params = urllib.parse.urlencode({
"url": "https://www.youtube.com/watch?v=xxxxxxxxxxx",
"format": "text",
})
headers = {}
req = urllib.request.Request(f"{BASE}/api/v1/transcript?{params}", headers=headers)
try:
with urllib.request.urlopen(req, timeout=300) as res:
print(res.read().decode())
except urllib.error.HTTPError as err:
error = json.load(err)["error"]
raise SystemExit(f"{error['code']}: {error['message']} {error.get('hint', '')}")npx -y vid2context get 'https://www.youtube.com/watch?v=xxxxxxxxxxx' --format text{
"name": "get_transcript",
"arguments": {
"url": "https://www.youtube.com/watch?v=xxxxxxxxxxx",
"format": "text"
}
}{
"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, without sending the whole transcript to a model.
- All transcript requests: languages, translation, sponsor removal and captions-only mode.