Introduction

PreviewProxy is an open-source, self-hosted image proxy and on-the-fly image transformer written in Rust. It sits between your application and upstream image sources, fetching, transforming, and caching images at request time - so you never need to pre-generate image variants or store multiple sizes.

What is PreviewProxy?​

When your application requests an image at a specific size or format, PreviewProxy:

1. Fetches the source image from an upstream source (HTTP URL, S3, local filesystem, or a named alias)
2. Applies any requested transforms (resize, format conversion, rotate, blur, and more)
3. Returns the result to the caller and stores it in a two-level cache (memory + disk) for subsequent requests

Because transforms are applied on demand and results are cached, your application only needs to store original images and can request any derivative variant via a simple URL.

Key Features​

• Multiple source backends - Proxy images from public or authenticated HTTP URLs, AWS S3 (or S3-compatible storage), the local filesystem, or short URL aliases
• On-the-fly transformation - Resize, convert formats, rotate, flip, blur, adjust brightness and contrast, apply watermarks, and more - all via URL parameters
• Two-level cache - L1 in-memory cache for hot images, L2 disk cache for longer-term storage, both with configurable TTL and size limits
• HMAC request signing - Optional HMAC-SHA256 signatures prevent unauthorized or tampered transform requests
• Disallow lists - Block specific input formats, output formats, or transform operations at the server level

Supported Formats​

Input Formats​

Format	Notes
JPEG
PNG
GIF	Including animated GIFs
WebP
AVIF
JXL	JPEG XL
BMP
TIFF
PDF	First page rendered as image
PSD	Adobe Photoshop
HEIC	Requires libheif
Video	Thumbnail extraction via ffmpeg (MP4, MOV, etc.)

Output Formats​

JPEG, PNG, GIF, WebP, AVIF, JXL, BMP, TIFF, ICO

Available Transforms​

Transform	Parameters	Description
Resize	w, h, fit	Resize to given width/height with optional fit mode
Format conversion	format	Convert to any supported output format
Rotate	rotate	Rotate by degrees (90, 180, 270)
Flip	flip	Flip horizontally or vertically
Blur	blur	Apply gaussian blur
Brightness	brightness	Adjust image brightness
Contrast	contrast	Adjust image contrast
Grayscale	grayscale	Convert to grayscale
Watermark	watermark	Overlay a watermark image
GIF frame selection	frame	Select a specific frame from an animated GIF
Video seek	seek	Extract thumbnail at a specific timestamp