> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bestvideotranscriptapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Uploading files

> Transcribe an audio or video file from your computer.

A file that isn't at a public link takes three steps: get an upload link, upload the file, then transcribe it.

```mermaid theme={null}
sequenceDiagram
  participant You
  participant API
  participant S as Storage
  You->>API: POST /v1/uploads
  API-->>You: uploadUrl + url
  You->>S: PUT file to uploadUrl
  You->>API: GET /v1/transcript?url=url
  API-->>You: Transcript
```

**1. Get an upload link**

```bash theme={null}
curl -X POST https://app.bestvideotranscriptapi.com/v1/uploads \
  -H "x-api-key: $VIDEO_TRANSCRIPT_API_KEY"
```

```json theme={null}
{
   "uploadUrl": "https://…amazonaws.com/uploads/…?X-Amz-Signature=…",
   "url": "https://…amazonaws.com/uploads/…?X-Amz-Signature=…",
   "expiresAt": "2026-11-03T10:00:00.000Z",
   "maxBytes": 2000000000
}
```

**2. Upload the file**

`PUT` the file to `uploadUrl`. The link is signed, so it doesn't take an API key.

```bash theme={null}
curl --fail -T recording.mp3 "<uploadUrl>"
```

**3. Transcribe it**

Pass `url` (not `uploadUrl`) to `GET /v1/transcript`, like any other link.

```bash theme={null}
curl -G https://app.bestvideotranscriptapi.com/v1/transcript \
  --data-urlencode "url=<url>" \
  -H "x-api-key: $VIDEO_TRANSCRIPT_API_KEY"
```

> [!TIP]
>
> `url` contains `&` and `=`, so URL-encode it. With curl, use `-G --data-urlencode` as above.

## Link lifetimes and size

| Item | Limit |
| - | - |
| `uploadUrl` | Works for 1 hour. |
| `url` | Works for 24 hours (`expiresAt`). Then we delete the file. |
| File size | Up to 2 GB. |

We don't keep your files. Each one is deleted when its `url` expires.

For a long video, upload just the audio track (mp3 or m4a). It's much smaller and transcribes the same.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.