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

# Compression Guide

> Optimize your storage with Imperial's auto-compression feature

## What is Auto-Compression?

Auto-compression automatically reduces image file sizes before upload, saving storage space while maintaining visual quality. This feature can reduce file sizes by 40-70% with minimal quality loss.

<Info>
  **Only images are compressed.** Videos are uploaded at their original quality to preserve playback performance.
</Info>

## How It Works

When auto-compression is enabled:

1. You upload an image
2. Imperial compresses it using Sharp (industry-leading image processor)
3. Compressed version is stored and served
4. You only pay for the compressed size

<CardGroup cols={3}>
  <Card title="Original" icon="image">
    2.4 MB
  </Card>

  <Card title="Compressed" icon="arrow-right" color="#8b5cf6">
    → Quality 65
  </Card>

  <Card title="Result" icon="check">
    1.1 MB (54% smaller)
  </Card>
</CardGroup>

## Quality Levels

Choose the right quality level for your use case:

<Tabs>
  <Tab title="High Quality (80)">
    **Best for:** Photography, portfolio work, detailed images

    * Minimal compression (\~40% size reduction)
    * Virtually no visible quality loss
    * Preserves fine details and gradients
    * Recommended for professional use

    **Example:**

    * Original: 3.2 MB → Compressed: 1.9 MB
  </Tab>

  <Tab title="Balanced (65)">
    **Best for:** General use, social media, websites

    * Moderate compression (\~55% size reduction)
    * Excellent quality-to-size ratio
    * Minor quality loss only visible on close inspection
    * **Default and recommended for most users**

    **Example:**

    * Original: 3.2 MB → Compressed: 1.4 MB
  </Tab>

  <Tab title="Optimized (50)">
    **Best for:** Thumbnails, icons, storage optimization

    * Maximum compression (\~70% size reduction)
    * Noticeable quality loss on detailed images
    * Perfect for storage-constrained accounts
    * Great for smaller images

    **Example:**

    * Original: 3.2 MB → Compressed: 1.0 MB
  </Tab>
</Tabs>

## Enabling Auto-Compression

<Steps>
  <Step title="Open Settings">
    Navigate to [Settings → Uploads](https://app.imperial.gay/settings) in your dashboard
  </Step>

  <Step title="Enable Auto-Compress">
    Toggle **Auto-Compress Images** to ON
  </Step>

  <Step title="Choose Quality">
    Select your preferred quality level (50-100)
  </Step>

  <Step title="Save Changes">
    Settings apply to all future uploads
  </Step>
</Steps>

<Tip>
  **Already uploaded images aren't affected.** Compression settings only apply to new uploads.
</Tip>

## Supported Formats

Compression works on these image formats:

| Format     | Compression | Notes                                    |
| ---------- | ----------- | ---------------------------------------- |
| **JPEG**   | ✅ Yes       | Most effective compression               |
| **PNG**    | ✅ Yes       | Good compression, preserves transparency |
| **WebP**   | ✅ Yes       | Already efficient, minor gains           |
| **GIF**    | ❌ No        | Animated GIFs uploaded as-is             |
| **Videos** | ❌ No        | All formats uploaded at original quality |

## Visual Comparison

Here's how different quality levels affect a typical photo:

<Tabs>
  <Tab title="Original (100)">
    ```
    File size: 3.2 MB
    Quality: Perfect
    Use case: Archives, print work
    ```

    Full detail preserved, maximum file size.
  </Tab>

  <Tab title="High Quality (80)">
    ```
    File size: 1.9 MB (41% smaller)
    Quality: Excellent
    Use case: Professional work, portfolios
    ```

    Virtually identical to original, significant size savings.
  </Tab>

  <Tab title="Balanced (65)">
    ```
    File size: 1.4 MB (56% smaller)
    Quality: Very Good
    Use case: Most websites, social media
    ```

    Minor quality loss only visible on pixel-peeping, great balance.
  </Tab>

  <Tab title="Optimized (50)">
    ```
    File size: 1.0 MB (69% smaller)
    Quality: Good
    Use case: Thumbnails, icons, storage optimization
    ```

    Visible compression artifacts on detailed areas, excellent space savings.
  </Tab>
</Tabs>

## When to Use Compression

### ✅ Recommended For

* **Screenshots** - Often contain large areas of solid color (excellent compression)
* **Web Graphics** - UI elements, icons, social media images
* **General Photography** - Personal photos, blog images
* **High-Volume Uploads** - Maximize your storage capacity

### ❌ Not Recommended For

* **Print Work** - When you need maximum quality for physical prints
* **Archival** - Original quality preservation is critical
* **Already Compressed** - Files from modern cameras/phones are already optimized
* **Medical/Scientific** - When detail accuracy is essential

## Storage Savings Calculator

Estimate your savings based on typical usage:

<Tabs>
  <Tab title="Light User">
    **Monthly uploads:** 50 images @ 2 MB each

    | Quality        | Size per Image | Total Storage | Savings |
    | -------------- | -------------- | ------------- | ------- |
    | Original       | 2.0 MB         | 100 MB        | -       |
    | High (80)      | 1.2 MB         | 60 MB         | 40%     |
    | Balanced (65)  | 0.9 MB         | 45 MB         | 55%     |
    | Optimized (50) | 0.6 MB         | 30 MB         | 70%     |
  </Tab>

  <Tab title="Regular User">
    **Monthly uploads:** 500 images @ 2 MB each

    | Quality        | Size per Image | Total Storage | Savings |
    | -------------- | -------------- | ------------- | ------- |
    | Original       | 2.0 MB         | 1000 MB       | -       |
    | High (80)      | 1.2 MB         | 600 MB        | 40%     |
    | Balanced (65)  | 0.9 MB         | 450 MB        | 55%     |
    | Optimized (50) | 0.6 MB         | 300 MB        | 70%     |

    **With Balanced (65):**

    * Starter (5 GB): \~11,000 images
    * Pro (10 GB): \~22,000 images
  </Tab>

  <Tab title="Power User">
    **Monthly uploads:** 2,000 images @ 2 MB each

    | Quality        | Size per Image | Total Storage | Savings |
    | -------------- | -------------- | ------------- | ------- |
    | Original       | 2.0 MB         | 4000 MB       | -       |
    | High (80)      | 1.2 MB         | 2400 MB       | 40%     |
    | Balanced (65)  | 0.9 MB         | 1800 MB       | 55%     |
    | Optimized (50) | 0.6 MB         | 1200 MB       | 70%     |

    **With Balanced (65):**

    * Pro (10 GB): \~5.5 months of uploads
    * Business (200 GB): \~111 months of uploads
  </Tab>
</Tabs>

## API Usage

### Check Compression Settings

Compression is automatically applied based on your dashboard settings. No additional parameters needed:

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

### Response Includes Compression Info

```json theme={null}
{
  "uploaded": [
    {
      "_id": "67d8f9a1b2c3d4e5f6789012",
      "url": "https://origin.imperial.gay/uploads/...",
      "filename": "photo.jpg",
      "originalFilename": "photo.jpg",
      "fileSize": 921600,
      "originalFileSize": 2048000,
      "compressed": true,
      "compressionQuality": 65,
      "mimeType": "image/jpeg"
    }
  ]
}
```

<Info>
  `fileSize` is what counts toward your storage limit. `originalFileSize` is just for reference.
</Info>

## Performance Impact

Compression happens server-side and adds minimal latency:

| File Size | Compression Time | Impact                   |
| --------- | ---------------- | ------------------------ |
| \< 1 MB   | \~50ms           | Negligible               |
| 1-5 MB    | \~100-200ms      | Minor                    |
| 5-10 MB   | \~300-500ms      | Noticeable               |
| > 10 MB   | \~500ms+         | Consider pre-compression |

<Tip>
  For very large files or batch uploads, consider compressing images before upload using tools like ImageOptim, TinyPNG, or Squoosh.
</Tip>

## Advanced Tips

### Format-Specific Optimization

<AccordionGroup>
  <Accordion title="JPEG Images" icon="image">
    * Most efficient format for compression
    * Quality 65-80 recommended for photos
    * Quality 50-65 for screenshots
    * Progressive encoding used automatically
  </Accordion>

  <Accordion title="PNG Images" icon="image">
    * Transparency preserved at all quality levels
    * Text and sharp edges remain crisp
    * Larger files benefit most from compression
    * Compression level 9 (maximum) used automatically
  </Accordion>

  <Accordion title="WebP Images" icon="image">
    * Already highly compressed format
    * Compression provides 10-30% additional savings
    * Maintains superior quality-to-size ratio
    * Recommended for modern web applications
  </Accordion>

  <Accordion title="GIF Images" icon="image">
    * Animated GIFs bypass compression
    * Static GIFs converted to PNG with compression
    * Consider converting GIFs to video for better results
  </Accordion>
</AccordionGroup>

### Bulk Optimization

If you have many uncompressed files:

1. **Download originals** from dashboard
2. **Re-upload with compression** enabled
3. **Delete uncompressed versions** to reclaim storage

Or use our bulk re-compress feature (coming soon).

### Testing Quality Levels

Try different quality levels with the same image:

```bash theme={null}
# Upload with current settings
curl -X POST https://api.imperial.gay/images/upload \
  -H "Authorization: Bearer YOUR_KEY" \
  -F "file=@test.jpg"

# Check response to see compressed size
# Adjust quality in dashboard
# Upload again to compare
```

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Does compression affect image dimensions?">
    No. Compression only reduces file size. Width and height remain unchanged.
  </Accordion>

  <Accordion title="Can I upload uncompressed images even with compression enabled?">
    No. If compression is enabled, all images are compressed. Disable it in settings for specific uploads.
  </Accordion>

  <Accordion title="What happens to transparency in PNG images?">
    Transparency is fully preserved at all quality levels. Alpha channels are maintained.
  </Accordion>

  <Accordion title="Can I re-compress already uploaded images?">
    Not currently. Compression happens during upload. Consider re-uploading with new settings if needed.
  </Accordion>

  <Accordion title="Why isn't my WebP file much smaller?">
    WebP is already an efficient format. Compression provides diminishing returns compared to JPEG/PNG.
  </Accordion>

  <Accordion title="Does compression slow down uploads?">
    Slightly. Most images add 50-200ms. Network transfer time is usually the bottleneck.
  </Accordion>
</AccordionGroup>

## Best Practices

<Steps>
  <Step title="Start with Balanced (65)">
    This provides the best quality-to-size ratio for most use cases
  </Step>

  <Step title="Test with Sample Images">
    Upload test images at different quality levels to find your sweet spot
  </Step>

  <Step title="Adjust Per Use Case">
    Use High (80) for important work, Optimized (50) when maximizing storage
  </Step>

  <Step title="Monitor Storage Usage">
    Check your dashboard to see how much space compression saves
  </Step>

  <Step title="Consider Format">
    JPEG compresses better than PNG for photos. PNG better for graphics with text.
  </Step>
</Steps>

## Related Resources

<CardGroup cols={2}>
  <Card title="Storage & Operations" icon="hard-drive" href="/operations">
    Learn how storage counts toward your limit
  </Card>

  <Card title="Pricing & Tiers" icon="dollar-sign" href="/pricing">
    Compare storage limits across tiers
  </Card>

  <Card title="Upload API" icon="cloud-arrow-up" href="/api-reference/endpoint/create">
    Technical details of the upload endpoint
  </Card>

  <Card title="Settings" icon="gear" href="https://app.imperial.gay/settings">
    Configure compression in your dashboard
  </Card>
</CardGroup>