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

**Upload an audio file** (`POST /api/v1/uploads`): Returns an input, upload:<sha256>, that every route taking url accepts for the next hour.

```bash
curl https://vid2context.com/api/v1/uploads \
  -F file=@apollo11-small-step.mp3
```

Response recorded on 2026-11-14 (HTTP 201 Created):

```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](https://vid2context.com/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.

**Transcribe the upload** (`GET /api/v1/transcript`): The input comes from the upload above once you run it. Uploads are transcribed by the speech-to-text chain.

```bash
curl -G https://vid2context.com/api/v1/transcript \
  --data-urlencode url=upload:9dd76462aaf0e20bd4984c7cb49f092d667ea7bbcb065d46814d570460ec89d7 \
  --data-urlencode format=srt
```

Response recorded on 2026-11-14 (HTTP 200 OK):

```text
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.

**Import a transcript you already have** (`POST /api/v1/imports`): Parses SRT, WebVTT, JSON segments or plain text into a VideoContext with origin "imported". Hosted servers return it without saving.

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

Response recorded on 2026-11-15 (HTTP 201 Created):

```json
{
  "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": {
```

(89 more lines; run the request to see them.)
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](https://vid2context.com/docs/guides/local-files.md) covers formats, ffmpeg and direct media URLs.
