Compression Guide

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.

Only images are compressed. Videos are uploaded at their original quality to preserve playback performance.

How It Works

When auto-compression is enabled:

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

Original

2.4 MB

Compressed

→ Quality 65

Result

1.1 MB (54% smaller)

Quality Levels

Choose the right quality level for your use case:

High Quality (80)
Balanced (65)
Optimized (50)

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

Enabling Auto-Compression

Open Settings

Navigate to Settings → Uploads in your dashboard

Enable Auto-Compress

Toggle Auto-Compress Images to ON

Choose Quality

Select your preferred quality level (50-100)

Save Changes

Settings apply to all future uploads

Already uploaded images aren’t affected. Compression settings only apply to new uploads.

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:

Original (100)
High Quality (80)
Balanced (65)
Optimized (50)

File size: 3.2 MB
Quality: Perfect
Use case: Archives, print work

Full detail preserved, maximum file size.

File size: 1.9 MB (41% smaller)
Quality: Excellent
Use case: Professional work, portfolios

Virtually identical to original, significant size savings.

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.

File size: 1.0 MB (69% smaller)
Quality: Good
Use case: Thumbnails, icons, storage optimization

Visible compression artifacts on detailed areas, excellent space savings.

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:

Light User
Regular User
Power 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%

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

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

API Usage

Check Compression Settings

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

curl -X POST https://api.imperial.gay/images/upload \
  -H "Authorization: Bearer YOUR_KEY" \
  -F "[email protected]"

Response Includes Compression Info

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

fileSize is what counts toward your storage limit. originalFileSize is just for reference.

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

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

Advanced Tips

Format-Specific Optimization

JPEG Images

Most efficient format for compression
Quality 65-80 recommended for photos
Quality 50-65 for screenshots
Progressive encoding used automatically

PNG Images

Transparency preserved at all quality levels
Text and sharp edges remain crisp
Larger files benefit most from compression
Compression level 9 (maximum) used automatically

WebP Images

Already highly compressed format
Compression provides 10-30% additional savings
Maintains superior quality-to-size ratio
Recommended for modern web applications

GIF Images

Animated GIFs bypass compression
Static GIFs converted to PNG with compression
Consider converting GIFs to video for better results

Bulk Optimization

If you have many uncompressed files:

Download originals from dashboard
Re-upload with compression enabled
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:

# Upload with current settings
curl -X POST https://api.imperial.gay/images/upload \
  -H "Authorization: Bearer YOUR_KEY" \
  -F "[email protected]"

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

Frequently Asked Questions

Does compression affect image dimensions?

No. Compression only reduces file size. Width and height remain unchanged.

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.

What happens to transparency in PNG images?

Transparency is fully preserved at all quality levels. Alpha channels are maintained.

Can I re-compress already uploaded images?

Not currently. Compression happens during upload. Consider re-uploading with new settings if needed.

Why isn't my WebP file much smaller?

WebP is already an efficient format. Compression provides diminishing returns compared to JPEG/PNG.

Does compression slow down uploads?

Slightly. Most images add 50-200ms. Network transfer time is usually the bottleneck.

Best Practices

Start with Balanced (65)

This provides the best quality-to-size ratio for most use cases

Test with Sample Images

Upload test images at different quality levels to find your sweet spot

Adjust Per Use Case

Use High (80) for important work, Optimized (50) when maximizing storage

Monitor Storage Usage

Check your dashboard to see how much space compression saves

Consider Format

JPEG compresses better than PNG for photos. PNG better for graphics with text.

Storage & Operations

Learn how storage counts toward your limit

Pricing & Tiers

Compare storage limits across tiers

Upload API

Technical details of the upload endpoint

Settings

Configure compression in your dashboard

Getting Started

Guides

SDKs & Libraries

Reference

Key Features

What is Auto-Compression?

How It Works

Original

Compressed

Result

Quality Levels

Enabling Auto-Compression

Supported Formats

Visual Comparison

When to Use Compression

✅ Recommended For

❌ Not Recommended For

Storage Savings Calculator

API Usage

Check Compression Settings

Response Includes Compression Info

Performance Impact

Advanced Tips

Format-Specific Optimization

Bulk Optimization

Testing Quality Levels

Frequently Asked Questions

Best Practices

Storage & Operations

Pricing & Tiers

Upload API

Settings

Getting Started

Guides

SDKs & Libraries

Reference

Key Features

​What is Auto-Compression?

​How It Works

Original

Compressed

Result

​Quality Levels

​Enabling Auto-Compression

​Supported Formats

​Visual Comparison

​When to Use Compression

​✅ Recommended For

​❌ Not Recommended For

​Storage Savings Calculator

​API Usage

​Check Compression Settings

​Response Includes Compression Info

​Performance Impact

​Advanced Tips

​Format-Specific Optimization

​Bulk Optimization

​Testing Quality Levels

​Frequently Asked Questions

​Best Practices

​Related Resources

Storage & Operations

Pricing & Tiers

Upload API

Settings

What is Auto-Compression?

How It Works

Quality Levels

Enabling Auto-Compression

Supported Formats

Visual Comparison

When to Use Compression

✅ Recommended For

❌ Not Recommended For

Storage Savings Calculator

API Usage

Check Compression Settings

Response Includes Compression Info

Performance Impact

Advanced Tips

Format-Specific Optimization

Bulk Optimization

Testing Quality Levels

Frequently Asked Questions

Best Practices

Related Resources