Examples

Your own files

Upload a file

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"
}

Transcribe the upload

Run the upload first: its input fills in this field.

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.

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.

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.

Your own audio and video files covers size limits, how long uploads last and local paths.

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).