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

# Upload Media

> Upload images and videos to your Imperial account

## Request

### Headers

<ParamField header="Authorization" type="string" required>
  Your authentication token in one of these formats: - **API Key (Pro/Business)**: `Bearer
      imperial_live_xxxxxxxxxxxxx` - **Upload Key (Free/Starter)**: `Bearer
      imperial_upload_xxxxxxxxxxxxx` See [Authentication](/api-reference/introduction) for more details.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `multipart/form-data` for file uploads
</ParamField>

### Body

<ParamField body="file" type="file" required>
  The image or video file to upload. Supports: - **Images**: JPEG, PNG, WebP, GIF - **Videos**: MP4,
  WebM, MOV, AVI
</ParamField>

## Response

<ResponseField name="_id" type="string">
  Unique identifier for the upload
</ResponseField>

<ResponseField name="url" type="string">
  Direct CDN URL to access the uploaded file
</ResponseField>

<ResponseField name="thumbnailUrl" type="string">
  Thumbnail URL (generated automatically for videos)
</ResponseField>

<ResponseField name="filename" type="string">
  The stored filename
</ResponseField>

<ResponseField name="originalFilename" type="string">
  The original filename before upload
</ResponseField>

<ResponseField name="fileSize" type="number">
  File size in bytes
</ResponseField>

<ResponseField name="mimeType" type="string">
  MIME type of the uploaded file (e.g., `image/jpeg`, `video/mp4`)
</ResponseField>

<ResponseField name="compressed" type="boolean">
  Whether the file was compressed (only for images with auto-compress enabled)
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp of upload
</ResponseField>

## Example Requests

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.imperial.gay/images/upload \
    -H "Authorization: Bearer imperial_live_xxxxxxxxxxxxx" \
    -F "file=@cat.jpg"
  ```

  ```javascript Node.js theme={null}
  const FormData = require("form-data");
  const fs = require("fs");
  const axios = require("axios");

  const form = new FormData();
  form.append("file", fs.createReadStream("cat.jpg"));

  const response = await axios.post("https://api.imperial.gay/images/upload", form, {
    headers: {
      Authorization: "Bearer imperial_live_xxxxxxxxxxxxx",
      ...form.getHeaders(),
    },
  });

  console.log(response.data);
  ```

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

  url = 'https://api.imperial.gay/images/upload'
  headers = {'Authorization': 'Bearer imperial_live_xxxxxxxxxxxxx'}
  files = {'file': open('cat.jpg', 'rb')}

  response = requests.post(url, headers=headers, files=files)
  print(response.json())
  ```
</CodeGroup>

## Example Response

```json theme={null}
{
  "_id": "67d8f9a1b2c3d4e5f6789012",
  "url": "https://origin.imperial.gay/uploads/user-id/67d8f9a1b2c3d4e5f6789012-cat.jpg",
  "filename": "67d8f9a1b2c3d4e5f6789012-cat.jpg",
  "originalFilename": "cat.jpg",
  "fileSize": 245678,
  "mimeType": "image/jpeg",
  "compressed": true,
  "createdAt": "2026-01-07T12:34:56.789Z"
}
```

## Video Upload Response

When uploading a video, a thumbnail is automatically generated:

```json theme={null}
{
  "_id": "67d8f9a1b2c3d4e5f6789013",
  "url": "https://origin.imperial.gay/uploads/user-id/67d8f9a1b2c3d4e5f6789013-video.mp4",
  "thumbnailUrl": "https://origin.imperial.gay/uploads/user-id/thumbs/67d8f9a1b2c3d4e5f6789013-thumb.jpg",
  "filename": "67d8f9a1b2c3d4e5f6789013-video.mp4",
  "originalFilename": "video.mp4",
  "fileSize": 5242880,
  "mimeType": "video/mp4",
  "compressed": false,
  "createdAt": "2026-01-07T12:35:00.123Z"
}
```

## Error Responses

### Storage Limit Exceeded

```json theme={null}
{
  "error": "Storage limit exceeded. You've used 4.8 GB of 5 GB.",
  "statusCode": 413
}
```

### Invalid File Type

```json theme={null}
{
  "error": "Only images and videos are allowed",
  "statusCode": 400
}
```

### Unauthorized

```json theme={null}
{
  "error": "Unauthorized",
  "statusCode": 401
}
```

## Features

### Auto-Compression

Enable auto-compression in your [Dashboard Settings](https://app.imperial.gay/settings) to automatically compress images on upload:

* **JPEG**: Compressed with customizable quality (default: 80%)
* **PNG**: Optimized compression level 9
* **WebP**: Compressed with quality setting

Videos are never compressed to preserve quality.

### Batch Uploads

You can upload multiple files in a single request by including multiple `file` fields:

```bash theme={null}
curl -X POST https://api.imperial.gay/images/upload \
  -H "Authorization: Bearer imperial_live_xxxxxxxxxxxxx" \
  -F "file=@image1.jpg" \
  -F "file=@image2.jpg" \
  -F "file=@image3.jpg"
```

The response will contain an array of upload results.

### Storage Management

Uploads count towards your storage limit based on your subscription tier:

| Tier     | Storage | Monthly Operations |
| -------- | ------- | ------------------ |
| Free     | 1 GB    | 10,000             |
| Starter  | 5 GB    | 100,000            |
| Pro      | 10 GB   | 1,000,000          |
| Business | 200 GB  | 5,000,000          |

<Tip>
  Upgrade your plan in the [Dashboard](https://app.imperial.gay/settings) to get more storage and
  operations.
</Tip>