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

# File uploads

> How to upload images and videos before creating a pre-test.

Creating a pre-test takes an `uploadId`, never a URL. Uploading has three steps: request the address, upload the file and use the `uploadId`.

## Types and sizes

| Type (`contentType`) | Extension | Maximum size |
| - | - | - |
| `image/png` | png | 25 MB |
| `image/jpeg` | jpg | 25 MB |
| `image/webp` | webp | 25 MB |
| `image/gif` | gif | 25 MB |
| `video/mp4` | mp4 | 200 MB |
| `video/quicktime` | mov | 200 MB |

Videos are at most **30 seconds** long. The duration is read from the file before any charge. Above that, creation responds [`video_too_long`](https://docs.myunite.ai/en/errors#video_too_long) and no quota unit is used.

Other types respond [`upload_invalid`](https://docs.myunite.ai/en/errors#upload_invalid). A size above the limit responds [`file_too_large`](https://docs.myunite.ai/en/errors#file_too_large).

## 1. Request the upload address

Requires the `pretests:write` scope.

```bash curl theme={null}
SIZE=$(wc -c < summer-urban-clock.mp4 | tr -d ' ')

curl -s -X POST https://myunite.ai/api/v1/uploads \
  -H "Authorization: Bearer $UNITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"contentType\":\"video/mp4\",\"sizeBytes\":$SIZE,\"filename\":\"summer-urban-clock.mp4\"}" \
  -o upload.json

export UPLOAD_ID=$(jq -r '.uploadId' upload.json)
export UPLOAD_URL=$(jq -r '.uploadUrl' upload.json)
export CACHE_CONTROL=$(jq -r '.headers["Cache-Control"]' upload.json)
```

```javascript JavaScript theme={null}
const res = await fetch("https://myunite.ai/api/v1/uploads", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.UNITE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    contentType: "video/mp4",
    sizeBytes: 8123456,
    filename: "summer-urban-clock.mp4",
  }),
});
const target = await res.json();
```

```python Python theme={null}
import os
import requests

target = requests.post(
    "https://myunite.ai/api/v1/uploads",
    headers={"Authorization": f"Bearer {os.environ['UNITE_API_KEY']}"},
    json={
        "contentType": "video/mp4",
        "sizeBytes": 8123456,
        "filename": "summer-urban-clock.mp4",
    },
).json()
```

The response carries `uploadId`, `uploadUrl`, `method` (always `PUT`), `headers` and `expiresAt`. The URL is valid for **15 minutes**. If it expires, request another one.

## 2. Upload the file

Make a `PUT` to the `uploadUrl` with the file content as the body.

> [!WARNING]
>
> Send **all** the headers in `headers`, with exactly the same values, including `Cache-Control`. If a header is missing or a value differs, the upload fails.

Do not send the `Authorization` header on this call: the URL already carries the authorization.

```bash curl theme={null}
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: video/mp4" \
  -H "Cache-Control: $CACHE_CONTROL" \
  --data-binary @summer-urban-clock.mp4
```

```javascript JavaScript theme={null}
import { readFile } from "node:fs/promises";

const put = await fetch(target.uploadUrl, {
  method: target.method,
  headers: target.headers, // all of them, unchanged
  body: await readFile("summer-urban-clock.mp4"),
});
if (!put.ok) throw new Error(`Upload failed: ${put.status}`);
```

```python Python theme={null}
with open("summer-urban-clock.mp4", "rb") as f:
    put = requests.put(target["uploadUrl"], headers=target["headers"], data=f)
put.raise_for_status()
```

## 3. Use the `uploadId`

Pass the `uploadId` when you [create the pre-test](https://docs.myunite.ai/en/quickstart.md). On creation, Unite checks the uploaded file:

* If the file does not exist (you did not upload it, or the `uploadId` belongs to another workspace), the response is [`upload_not_found`](https://docs.myunite.ai/en/errors#upload_not_found).
* If the content does not match the type, or the video has no readable duration, the response is [`upload_invalid`](https://docs.myunite.ai/en/errors#upload_invalid).
* The declared size is only a hint. The limit applies to the real size of the file.

The same `uploadId` can be used in more than one pre-test of the same workspace.


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