Your own files
Upload a file
/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"
}Transcribe the upload
Run the upload first: its input fills in this field.
/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.
Import a transcript you already have
When you already have a transcript (captions you corrected, a file from your editor, a transcript you have the rights to), import it instead of transcribing. Edit the text and run it: your wording and timing are kept, and origin is imported so nothing downstream mistakes it for the platform's captions.
/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.
Your own audio and video files covers size limits, how long uploads last and local paths.