Call the API from your code
Every block on these pages has JavaScript and Python versions of its request. This tutorial covers what those short snippets leave out: how errors look, which ones to retry, and the headers that save work.
Errors have one shape
Every route answers errors with the same body: a stable code to branch on, a message, a hint that says how to recover, and attempts, every provider and rung that ran. Run this one, a video id that does not exist:
/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)"
}
]
}The status follows the code:
| Code | Status | Retry? |
|---|---|---|
bad-request, unsupported-input |
400 | No: fix the request |
unauthorized / forbidden |
401 / 403 | No: check the API key and its scope |
unavailable |
403 | No: private, members-only or region-locked |
not-found |
404 | No |
too-large |
413 | No: send less |
no-transcript |
422 | Later, or with mode=stt when captions are missing |
rate-limited |
429 | Yes, after Retry-After seconds |
all-rungs-failed, upstream |
502 | Yes, with backoff |
auth |
502 | No: a key the server holds for an upstream service failed; its operator fixes it |
blocked, no-provider |
503 | blocked yes, later; no-provider no |
timeout |
504 | Yes, or ask for less |
The full list lives in the HTTP API contract.
A client that retries
This is a complete client for Node 22 or newer (or a browser): it retries rate limits and upstream failures, honours Retry-After, sends a key when one is set, and throws an error that keeps the code and the hint.
const BASE = process.env.VID2CONTEXT_URL ?? 'http://127.0.0.1:8787';
const KEY = process.env.VID2CONTEXT_API_KEY;
const RETRY = new Set([429, 502, 503, 504]);
const FINAL = new Set(['no-provider', 'auth']);
export class ApiError extends Error {
constructor(status, body) {
super(`${body.error?.code ?? status}: ${body.error?.message ?? 'request failed'}`);
this.status = status;
this.code = body.error?.code;
this.hint = body.error?.hint;
this.attempts = body.attempts ?? [];
}
}
export async function api(path, { params, body, tries = 4 } = {}) {
const url = new URL(`/api/v1${path}`, BASE);
for (const [k, v] of Object.entries(params ?? {})) url.searchParams.set(k, String(v));
const headers = { ...(KEY ? { Authorization: `Bearer ${KEY}` } : {}), ...(body ? { 'Content-Type': 'application/json' } : {}) };
for (let attempt = 1; ; attempt++) {
const res = await fetch(url, { method: body ? 'POST' : 'GET', headers, body: body ? JSON.stringify(body) : undefined });
if (res.ok) return res.headers.get('content-type')?.includes('json') ? res.json() : res.text();
const error = await res.json().catch(() => ({}));
if (!RETRY.has(res.status) || FINAL.has(error.error?.code) || attempt >= tries) throw new ApiError(res.status, error);
const wait = Number(res.headers.get('retry-after')) || 2 ** attempt;
await new Promise((r) => setTimeout(r, wait * 1000));
}
}
console.log(await api('/transcript', { params: { url: 'https://www.youtube.com/watch?v=jNQXAC9IVRw', timestamps: 1 } }));The same in Python, with the standard library only:
import json
import os
import time
import urllib.error
import urllib.parse
import urllib.request
BASE = os.environ.get("VID2CONTEXT_URL", "http://127.0.0.1:8787")
KEY = os.environ.get("VID2CONTEXT_API_KEY")
RETRY = {429, 502, 503, 504}
FINAL = {"no-provider", "auth"}
class ApiError(Exception):
def __init__(self, status, body):
error = body.get("error", {})
super().__init__(f"{error.get('code', status)}: {error.get('message', 'request failed')}")
self.status, self.code, self.hint = status, error.get("code"), error.get("hint")
self.attempts = body.get("attempts", [])
def api(path, params=None, body=None, tries=4):
url = f"{BASE}/api/v1{path}"
if params:
url += "?" + urllib.parse.urlencode(params)
headers = {"Authorization": f"Bearer {KEY}"} if KEY else {}
data = None
if body is not None:
headers["Content-Type"] = "application/json"
data = json.dumps(body).encode()
for attempt in range(1, tries + 1):
req = urllib.request.Request(url, data=data, headers=headers, method="POST" if data else "GET")
try:
with urllib.request.urlopen(req, timeout=300) as res:
text = res.read().decode()
return json.loads(text) if "json" in res.headers.get("Content-Type", "") else text
except urllib.error.HTTPError as err:
try:
error = json.load(err)
except ValueError:
error = {}
code = error.get("error", {}).get("code")
if err.code not in RETRY or code in FINAL or attempt == tries:
raise ApiError(err.code, error) from None
time.sleep(float(err.headers.get("Retry-After") or 2**attempt))
print(api("/transcript", {"url": "https://www.youtube.com/watch?v=jNQXAC9IVRw", "timestamps": 1}))API keys
A server open to the internet sets VID2CONTEXT_API_KEYS; then every route except /health needs Authorization: Bearer <key>. A key can be limited to a scope: read allows GET and the POST routes that only compute an answer (/pack, /bundle, /ask, /research and the like), write adds every other change, and admin allows everything. A missing or wrong key answers 401, a key without the scope 403. The gear button on any block sets a key for the runnable examples.
Save work with ETags
/context sends an ETag. Keep it with your copy and send it back as If-None-Match; when nothing changed, the server answers 304 with no body.
/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.
curl -i 'https://vid2context.com/api/v1/context?url=jNQXAC9IVRw' \
-H 'If-None-Match: "<the etag you kept>"'Contexts are also saved in the server's library, so asking again for a video you already fetched is fast even without the header. Add refresh=1 to rebuild one, for example after the creator fixed the captions.
Long work: jobs and timeouts
- A request that runs longer than
VID2CONTEXT_REQUEST_TIMEOUT_MS(5 minutes by default) answers504 timeout. - Briefs and extractions run as jobs on servers that have a queue:
202with a Job, thenGET /api/v1/jobs/{id}untilstatusissucceeded,failedorcanceled.GET /api/v1/jobs/{id}/eventsstreams the progress as server-sent events instead of polling. Cited answers and briefs runs one. - Every response carries
X-Request-Id; send your own (up to 128 characters ofA-Za-z0-9._:-) to find a request in the server's access log.
The whole API
GET /api/v1/openapi.json describes every route the server has, generated from the routes themselves, for client generators and agents. The HTTP API guide and the contract describe each one.