Tutorials

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.

POST/api/v1/uploadsUpload an audio file

Returns an input, upload:<sha256>, that every route taking url accepts for the next hour.

Sending: apollo11-small-step.mp3 (sample)
bash
curl https://vid2context.com/api/v1/uploads \
  -F file=@apollo11-small-step.mp3
Recorded response: 201 Created, 9 ms, 2026-11-14
content-type application/json
{
  "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.

GET/api/v1/transcriptTranscribe the upload

The input comes from the upload above once you run it. Uploads are transcribed by the speech-to-text chain.

Filled in when you run "Upload an audio file" above.
bash
curl -G https://vid2context.com/api/v1/transcript \
  --data-urlencode url=upload:9dd76462aaf0e20bd4984c7cb49f092d667ea7bbcb065d46814d570460ec89d7 \
  --data-urlencode format=srt
Recorded response: 200 OK, 1.9 s, 2026-11-14
content-type application/x-subrip; charset=utf-8
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.

POST/api/v1/importsImport a transcript you already have

Parses SRT, WebVTT, JSON segments or plain text into a VideoContext with origin "imported". Hosted servers return it without saving.

The video the transcript belongs to; its metadata comes from the platform.
Edit a line and run it again: the import keeps your wording and timing.
BCP-47, for example en, de or pt-BR
bash
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"
}'
Recorded response: 201 Created, 865 ms, 2026-11-15
content-type application/jsonx-ratelimit-remaining 52
{
  "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:

sh
npx -y vid2context ./meeting.mp4 --timestamps

Public servers refuse local paths (VID2CONTEXT_PUBLIC=1), so on those, upload. The local files guide covers formats, ffmpeg and direct media URLs.

Where examples run

Any vid2context server: your own deployment, or one started from a clone of the repo with VID2CONTEXT_CORS_ORIGINS=this origin npm run start:server (it listens on http://127.0.0.1:8787). The CORS variable lets this page read its responses.

Only for servers that set VID2CONTEXT_API_KEYS. Sent as Authorization: Bearer, kept in this tab's session storage, and never written into the snippets (they read $VID2CONTEXT_API_KEY).