Your own audio and video files
Not every video is on a platform. A recording of a meeting, a lecture you filmed, a podcast you downloaded: upload the file, and every route that takes a url accepts it.
1. Upload the file
POST /uploads takes a multipart form with one field, file. The answer holds an input, upload: followed by the file's SHA-256, that stands for the file in later requests.
The block sends a real 24-second clip of Neil Armstrong stepping onto the Moon (public domain, from NASA) unless you choose a file of your own.
/api/v1/uploadsUpload an audio fileReturns an input, upload:<sha256>, that every route taking url accepts for the next hour.
curl https://vid2context.com/api/v1/uploads \
-F file=@apollo11-small-step.mp3import { readFile } from 'node:fs/promises';
const BASE = 'https://vid2context.com';
const form = new FormData();
form.append('file', new Blob([await readFile('apollo11-small-step.mp3')]), 'apollo11-small-step.mp3');
const res = await fetch(`${BASE}/api/v1/uploads`, {
method: 'POST',
body: form,
});
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
import uuid
BASE = "https://vid2context.com"
boundary = uuid.uuid4().hex
with open("apollo11-small-step.mp3", "rb") as f:
payload = f.read()
data = (
f'--{boundary}\r\nContent-Disposition: form-data; name="file"; filename="apollo11-small-step.mp3"\r\n'
'Content-Type: application/octet-stream\r\n\r\n'
).encode() + payload + f"\r\n--{boundary}--\r\n".encode()
headers = {"Content-Type": f"multipart/form-data; boundary={boundary}"}
req = urllib.request.Request(f"{BASE}/api/v1/uploads", data=data, headers=headers, method="POST")
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', '')}"){
"input": "upload:9dd76462aaf0e20bd4984c7cb49f092d667ea7bbcb065d46814d570460ec89d7",
"filename": "apollo11-small-step.mp3",
"bytes": 145412,
"mimeType": "audio/mpeg",
"expiresAt": "2026-11-14T19:48:13.431Z"
}Facts worth knowing before you upload something large:
- The default size cap is 100 MB (
VID2CONTEXT_MAX_UPLOAD_MB), the request limit of the Workers free plan. - An upload is kept for 60 minutes (
VID2CONTEXT_UPLOAD_TTL_MIN). The same bytes uploaded again are the same upload, with its time extended. - Speech-to-text services take about 25 MB per request, so a video file is best reduced to compressed mono audio first: about 30 MB per hour at 64 kbit/s. The web app does this in your browser before it uploads.
2. Transcribe it
Run the upload above and its input fills in the field below. Uploads have no captions, so the transcript comes from the speech-to-text chain.
/api/v1/transcriptTranscribe the uploadThe input comes from the upload above once you run it. Uploads are transcribed by the speech-to-text chain.
curl -G https://vid2context.com/api/v1/transcript \
--data-urlencode url=upload:9dd76462aaf0e20bd4984c7cb49f092d667ea7bbcb065d46814d570460ec89d7 \
--data-urlencode format=srtconst BASE = 'https://vid2context.com';
const params = new URLSearchParams({
url: 'upload:9dd76462aaf0e20bd4984c7cb49f092d667ea7bbcb065d46814d570460ec89d7',
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": "upload:9dd76462aaf0e20bd4984c7cb49f092d667ea7bbcb065d46814d570460ec89d7",
"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', '')}")1
00:00:03,500 --> 00:00:05,160
I'm going to step off the limb now.
2
00:00:14,980 --> 00:00:23,040
That's one small step for man,
one giant leap for mankind.
An upload's transcript is kept next to the upload and expires with it; it is never saved in the library.
3. Or import a transcript you already have
Sometimes the transcript exists and only needs to get in: captions you fixed by hand, an SRT from your video editor, a transcript a speaker sent you. POST /imports takes the text (SRT, WebVTT, JSON segments or plain text, up to 5 MB) and the video it belongs to, parses it, and returns a VideoContext whose transcript.origin is imported, so a model or a later step can tell it apart from captions read from the platform.
The block holds the real captions of "Me at the zoo". Change a line, run it, and the change is in the segments that come back.
/api/v1/importsImport a transcript you already haveParses SRT, WebVTT, JSON segments or plain text into a VideoContext with origin "imported". Hosted servers return it without saving.
curl https://vid2context.com/api/v1/imports \
-H 'Content-Type: application/json' \
-d '{
"url": "https://www.youtube.com/watch?v=jNQXAC9IVRw",
"text": "1\n00:00:01,200 --> 00:00:03,360\nAll right, so here we are,\nin front of the elephants\n\n2\n00:00:05,318 --> 00:00:07,974\nthe cool thing about these guys\nis that they have really...\n\n3\n00:00:07,974 --> 00:00:12,616\nreally really long trunks\n\n4\n00:00:12,616 --> 00:00:14,367\nand that'\''s cool\n\n5\n00:00:14,421 --> 00:00:15,733\n(baaaaaaaaaaahhh!!)\n\n6\n00:00:16,881 --> 00:00:18,881\nand that'\''s pretty much all there is to say",
"language": "en"
}'const BASE = 'https://vid2context.com';
const body = {
url: 'https://www.youtube.com/watch?v=jNQXAC9IVRw',
text: '1\n00:00:01,200 --> 00:00:03,360\nAll right, so here we are,\nin front of the elephants\n\n2\n00:00:05,318 --> 00:00:07,974\nthe cool thing about these guys\nis that they have really...\n\n3\n00:00:07,974 --> 00:00:12,616\nreally really long trunks\n\n4\n00:00:12,616 --> 00:00:14,367\nand that\'s cool\n\n5\n00:00:14,421 --> 00:00:15,733\n(baaaaaaaaaaahhh!!)\n\n6\n00:00:16,881 --> 00:00:18,881\nand that\'s pretty much all there is to say',
language: 'en',
};
const res = await fetch(`${BASE}/api/v1/imports`, {
headers: { 'Content-Type': 'application/json' },
method: 'POST',
body: JSON.stringify(body),
});
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"
body = {
"url": "https://www.youtube.com/watch?v=jNQXAC9IVRw",
"text": "1\n00:00:01,200 --> 00:00:03,360\nAll right, so here we are,\nin front of the elephants\n\n2\n00:00:05,318 --> 00:00:07,974\nthe cool thing about these guys\nis that they have really...\n\n3\n00:00:07,974 --> 00:00:12,616\nreally really long trunks\n\n4\n00:00:12,616 --> 00:00:14,367\nand that's cool\n\n5\n00:00:14,421 --> 00:00:15,733\n(baaaaaaaaaaahhh!!)\n\n6\n00:00:16,881 --> 00:00:18,881\nand that's pretty much all there is to say",
"language": "en",
}
headers = {"Content-Type": "application/json"}
req = urllib.request.Request(f"{BASE}/api/v1/imports", data=json.dumps(body).encode(), headers=headers, method="POST")
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', '')}"){
"context": {
"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": 448610409,
"likeCount": 20139792,
"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": "imported",
"producer": "import/paste",
"segments": [
{
"startSec": 1.2,49 more lines not shown. Run it to see the whole response.
On a server you run, the import is saved in the library under the video's id, so later requests for that video answer with your transcript (saved in the response says so). Hosted servers (VID2CONTEXT_HOSTED=1) return the import without saving it, because their library is shared and an imported text is not verified.
Files on the server's own disk
A server you run yourself can also read local paths and file:// URLs directly, without an upload. The CLI does the same:
npx -y vid2context ./meeting.mp4 --timestampsPublic servers refuse local paths (VID2CONTEXT_PUBLIC=1), so on those, upload. The local files guide covers formats, ffmpeg and direct media URLs.