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

{% hint style="info" %}
**Note:** Some services like Google Merchant Center do not accept AVIF images. If you use Google Merchant feeds, see [Google Merchant Crawler](https://docs.smoxy.eu/en/sites/google-merchant-crawler) for details.
{% endhint %}

***

### 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. See [Cloudflare Setup](https://docs.smoxy.eu/en/sites/broken-reference).