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

# Custom Uploaders

> Configure Imperial Shot or ShareX to instantly upload screenshots and files

## Choose Your Uploader

Imperial offers two powerful ways to upload screenshots and files instantly:

<CardGroup cols={2}>
  <Card title="Imperial Shot" icon="rocket" color="#8b5cf6">
    **Recommended** - Native desktop app built for zero-latency uploads with smart editing
  </Card>

  <Card title="ShareX Config" icon="share-nodes" color="#6366f1">
    Pre-configured file for ShareX users on Windows
  </Card>
</CardGroup>

## Imperial Shot (Recommended)

Imperial Shot is our native desktop application designed for lightning-fast screenshot capture and instant uploads.

### Why Imperial Shot?

<CardGroup cols={2}>
  <Card title="Unmatched Speed" icon="bolt">
    Zero-latency uploads via optimized WebSocket pipeline with simultaneous encoding
  </Card>

  <Card title="Cross-Platform" icon="desktop">
    Works flawlessly on Windows, macOS, and Linux with native performance
  </Card>

  <Card title="Smart Editor" icon="pen-to-square">
    Annotate, crop, and blur sensitive info instantly before uploading
  </Card>

  <Card title="Secure Sync" icon="shield">
    Your uploads are instantly synced and secured in your private vault
  </Card>
</CardGroup>

### Installation

1. Visit the [Uploader page](https://app.imperial.gay/uploader) in your dashboard
2. Click **Download Installer** and choose your platform:
   * Windows (.exe)
   * macOS (.dmg)
   * Linux (.deb)
3. Run the installer and follow the setup wizard
4. Sign in with your Imperial credentials

### Features

**Native Performance**

* Lightweight C++ client with zero resource overhead
* Hardware-accelerated image processing
* Instant capture with customizable hotkeys

**Global Edge Network**

* Leverages Cloudflare's Enterprise routing
* R2 storage for lightning-fast delivery worldwide
* Automatic compression and optimization

**Built for Scale**

* Handles massive parallelism and batch uploads
* Uninterrupted backpressure handling under any load
* Smart retry logic for unstable connections

<Info>
  Imperial Shot is in active development. [Join our Discord](https://discord.gg/imperial) for early
  access updates.
</Info>

***

## ShareX Configuration

[ShareX](https://getsharex.com/) is a popular free, open-source screenshot tool for Windows. Configure it to work with Imperial in seconds.

### Get Your Upload Key

All Imperial users get an upload key for custom uploaders:

1. Log into your [Dashboard](https://app.imperial.gay)
2. Navigate to **Settings** → **Security**
3. Find your upload key (starts with `imperial_upload_`)
4. Copy it for use in your configuration

<Info>
  **Free & Starter users:** You'll use an upload key (`imperial_upload_`) which only works for
  uploading. **Pro & Business users:** You can use either an upload key or a full API key
  (`imperial_live_`) for uploads. Using an API key enables request analytics, upload latency
  tracking, and detailed logs in your dashboard.
</Info>

## Quick Setup

<Steps>
  <Step title="Get Your Config File">
    1. Log in to the [Imperial Dashboard](https://app.imperial.gay) 2. Navigate to **Uploader** in
       the sidebar 3. Click **Download Config** to get your pre-configured `.sxcu` file
  </Step>

  <Step title="Import to ShareX">
    **Option 1 (Easiest):** Double-click the downloaded `.sxcu` file **Option 2 (Manual):** 1. Open
    ShareX 2. Go to **Destinations** → **Custom uploader settings** 3. Click **Import** → **From
    file** 4. Select your downloaded `.sxcu` file
  </Step>

  <Step title="Set as Default">
    1. In ShareX, go to **Destinations** → **Image uploader** 2. Select **Imperial** from the list
    2. Done! Take a screenshot and watch it upload automatically
  </Step>
</Steps>

## Configuration Details

Your `.sxcu` file contains:

```json theme={null}
{
  "Name": "Imperial",
  "DestinationType": "ImageUploader, FileUploader",
  "RequestMethod": "POST",
  "RequestURL": "https://api.imperial.gay/images/upload",
  "Headers": {
    "Authorization": "Bearer imperial_upload_xxxxxxxxxxxxx"
  },
  "Body": "MultipartFormData",
  "FileFormName": "file",
  "URL": "$json:uploaded[0].url$"
}
```

<Warning>
  Your upload key is embedded in this file. Keep it secure and never share your `.sxcu` file
  publicly.
</Warning>

<Tip>
  Download a pre-configured `.sxcu` file from your [Uploader
  page](https://app.imperial.gay/uploader) with your upload key already included.
</Tip>

## Custom Hotkeys

Configure ShareX hotkeys for instant uploads:

1. Open ShareX → **Hotkey settings**
2. Add a new hotkey (e.g., `Ctrl + Shift + 3`)
3. Set **Task** to "Capture region" or your preferred capture method
4. Set **After capture** to "Upload image to host"

Popular hotkey configurations:

* `Ctrl + Shift + 3` - Capture region and upload
* `Ctrl + Shift + 4` - Capture active window and upload
* `Ctrl + Shift + 5` - Capture entire screen and upload

## Advanced Features

### Auto-Compression

Control image compression in your [Dashboard Settings](https://app.imperial.gay/settings):

<Tabs>
  <Tab title="High Quality (80)">
    Minimal compression, larger file sizes. Best for photography and detailed images.
  </Tab>

  <Tab title="Balanced (65)">
    Good balance between quality and file size. Recommended for most use cases.
  </Tab>

  <Tab title="Optimized (50)">
    Maximum compression, smaller file sizes. Perfect for saving storage space.
  </Tab>
</Tabs>

### Video Uploads

ShareX can also upload videos! Imperial automatically generates thumbnails for video files.

Supported formats: MP4, WebM, MOV, AVI

### Batch Uploads

Upload multiple files at once - Imperial handles batch uploads efficiently with progress tracking for each file.

## Manual Configuration

If you prefer to configure ShareX manually:

### Request Settings

* **Request URL:** `https://api.imperial.gay/images/upload`
* **Method:** POST
* **Body:** Multipart/form-data
* **File form name:** `file`

### Headers

```
Authorization: Bearer imperial_upload_xxxxxxxxxxxxx
```

<Info>
  Use your upload key from **Settings** → **Security**. Pro/Business users can also use their API
  keys.
</Info>

### Response URL

```
$json:uploaded[0].url$
```

### Error Handling

```
$json:error$
```

## Other Custom Uploaders

The same configuration works with other tools that support custom uploaders:

### Windows

* [ShareX](https://getsharex.com/) (Recommended)
* [Greenshot](https://getgreenshot.org/)
* [Lightshot](https://app.prntscr.com/)

### macOS

* [CleanShot X](https://cleanshot.com/)
* Configure as a custom destination

### Linux

* [Flameshot](https://flameshot.org/)
* [Spectacle](https://apps.kde.org/spectacle/)

### Browser Extensions

You can also create browser extensions using the same API endpoint.

## Response Format

Successful upload response:

```json theme={null}
{
  "uploaded": [
    {
      "_id": "67d8f9a1b2c3d4e5f6789012",
      "url": "https://origin.imperial.gay/uploads/user-id/67d8f9a1b2c3d4e5f6789012-screenshot.png",
      "filename": "screenshot.png",
      "size": 245824
    }
  ],
  "count": 1
}
```

The `uploaded[0].url` field contains your shareable CDN link.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Upload fails with 401 Unauthorized">
    Your upload key is invalid or expired. Options: - **Free/Starter users:** Regenerate your upload
    key in [Settings → Security](https://app.imperial.gay/settings) - **Pro/Business users:** Create
    a new API key in [Settings → API Keys](https://app.imperial.gay/api) or regenerate your upload
    key After regenerating, download a new `.sxcu` file or update your configuration manually.
  </Accordion>

  <Accordion title="Upload fails with 413 Storage Limit Exceeded">
    You've reached your storage limit. Either: - Delete old uploads to free up space - Upgrade your
    plan for more storage - Enable auto-compression to reduce file sizes
  </Accordion>

  <Accordion title="ShareX shows 'No response from server'">
    Check your internet connection and verify the API endpoint is
    `https://api.imperial.gay/images/upload` (not `http://`).
  </Accordion>

  <Accordion title="URL not copying to clipboard">
    Verify your response URL is set to: `$json:uploaded[0].url$`
  </Accordion>
</AccordionGroup>

## API Rate Limits

Your uploads count towards your monthly operations limit:

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

Each upload = 1 operation. Monitor your usage in the [Dashboard Stats](https://app.imperial.gay).

## Security Best Practices

<Warning>
  **Protect Your Upload Key** - Never commit `.sxcu` files to version control - Don't share
  screenshots of your ShareX settings - Regenerate your upload key if compromised
</Warning>

<Tip>
  **For Pro/Business Users** Create separate API keys for different use cases: - Use upload keys for
  ShareX and custom uploaders - Use full API keys for programmatic access - Revoke individual keys
  without affecting others
</Tip>

<Info>
  **Upload Key vs API Key** - **Upload keys** (`imperial_upload_`) can only upload files (no
  analytics) - **API keys** (`imperial_live_`) can access all endpoints + provide request analytics,
  latency tracking, and detailed logs (Pro/Business only) - Both work for uploading, but API keys
  give you visibility into performance and usage patterns
</Info>

## Next Steps

<CardGroup cols={2}>
  <Card title="API Reference" icon="code" href="/api-reference/endpoint/create">
    Full upload endpoint documentation
  </Card>

  <Card title="Dashboard" icon="house" href="https://app.imperial.gay">
    View your uploads and settings
  </Card>

  <Card title="Manage API Keys" icon="key" href="https://app.imperial.gay/api">
    Create and manage API keys
  </Card>

  <Card title="View Stats" icon="chart-line" href="https://app.imperial.gay">
    Monitor your usage and operations
  </Card>
</CardGroup>