Image Optimization

smoxy automatically optimizes images served through your site -- reducing file sizes without visible quality loss and converting images to modern formats like WebP and AVIF. This improves page load times and reduces bandwidth usage.

---

How It Works

When image optimization is enabled:

1. A visitor requests an image (e.g., product.jpg)
2. smoxy fetches the image from your origin
3. smoxy compresses the image and optionally converts it to WebP or AVIF
4. The optimized image is cached and served to the visitor
5. The original URL does not change -- format negotiation happens automatically via the Accept header

Supported input formats: JPEG, PNG

Supported output formats: JPEG, PNG, WebP, AVIF

---

Enabling Image Optimization

1. Navigate to your Site in smoxy
2. Open the Image Optimization settings
3. Toggle Image Optimization on
4. Configure quality and format settings
5. Save

---

Format Conversion

Convert to WebP

When enabled, smoxy converts JPEG and PNG images to WebP format for browsers that support it. WebP typically achieves 25--35% smaller file sizes compared to JPEG at the same visual quality.

Setting	Default
convert_to_webp	Enabled
webp_quality	75

Browsers that do not support WebP receive the optimized original format (JPEG or PNG).

Convert to AVIF

When enabled, smoxy converts JPEG and PNG images to AVIF format for browsers that support it. AVIF typically achieves even better compression than WebP.

Setting	Default
convert_to_avif	Enabled
avif_quality	50

Browsers that do not support AVIF fall back to WebP (if enabled), or the optimized original format.

INFO

Note: Some services like Google Merchant Center do not accept AVIF images. If you use Google Merchant feeds, see Google Merchant Crawler for details.

---

Quality Settings

Image optimization uses a quality range (min/max) to find the best balance between file size and visual quality. smoxy uses the SSIM (Structural Similarity Index) method to ensure compressed images remain visually identical to the originals.

JPEG

Setting	Range	Default	Description
jpeg_quality_min	1--100	40	Minimum acceptable quality (lower bound)
jpeg_quality_max	1--100	98	Maximum quality (upper bound)
jpeg_quality_target	0.0001--0.9999	0.9997	SSIM target -- higher means closer to the original

The SSIM target controls how aggressively smoxy compresses. The default of 0.9997 is very conservative -- nearly indistinguishable from the original. Lower the target for smaller files at the cost of slightly reduced quality.

PNG

Setting	Range	Default	Description
png_quality_min	1--100	40	Minimum acceptable quality
png_quality_max	1--100	98	Maximum quality

WebP

Setting	Range	Default	Description
webp_quality	1--100	75	Output quality for WebP conversion

AVIF

Setting	Range	Default	Description
avif_quality	1--100	50	Output quality for AVIF conversion

---

Per-Request Overrides

You can override image optimization settings for specific requests using Conditional Rules. This allows you to:

• Set different quality levels for mobile users
• Disable format conversion for specific paths
• Apply more aggressive compression for specific regions

Example: Reduce image quality for mobile visitors to save bandwidth:

Condition	Setting	Value
User Agent matches (Mobile|Android|iPhone)	JPEG Max Quality	75
User Agent matches (Mobile|Android|iPhone)	WebP Quality	65

---

Important Considerations

• Automatic format negotiation: smoxy checks the visitor's Accept header to determine which formats the browser supports. The URL stays the same -- only the response format changes.
• Cached per format: Optimized images are cached separately for each output format. A JPEG, WebP, and AVIF version of the same image can coexist in the cache.
• Only JPEG and PNG inputs: smoxy optimizes JPEG and PNG images. Other formats (GIF, SVG, etc.) are passed through without modification.
• Lossless is not supported: Image optimization always applies lossy compression. If you need pixel-perfect image delivery, disable optimization for those paths using a Conditional Rule.
• Cloudflare users: If you use Cloudflare in front of smoxy, disable Cloudflare's image optimization (Polish) to avoid double optimization.