> For the complete documentation index, see [llms.txt](https://docs.flashedgecdn.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flashedgecdn.com/flashedge-cdn-zone-tutorials/configuring-flashedge-optimizer.md).

# Configuring FlashEdge Optimizer

{% hint style="info" %}
FlashEdge Optimizer is a feature that is only available upon request.
{% endhint %}

Based on the UI screenshot provided, here is the updated documentation reflecting the new interface controls, including Image preset configuration, Separate mobile presets, Max width (px), Fit options, and the updated Enable Optimizer action button.<br>

## Enabling Image Optimization

Image Optimization is configured per zone. It lives in the Optimizer tab on your zone's detail page.<br>

### Enable

1. Open your zone and go to the Optimizer tab.
2. Toggle the Image Optimization switch on to open the configuration panel.
3. Choose an Image Origin dropdown option to define where FlashEdge fetches original images (e.g., FlashEdge Storage bucket, existing source server, or Custom URL).
4. Configure Image preset configuration:
   * Use separate mobile preset (recommended): Toggle this on if you want distinct settings for mobile devices. When turned off, the desktop preset applies to all devices.
   * Desktop preset (default) / Mobile preset settings:
     * Max width (px): Set a maximum pixel width. Images wider than this value are downscaled automatically. Leave empty to keep the original width.
     * Quality (1–100): Adjust the slider or value. The default of `80` balances detail and file size.
     * Fit: Select how the image resizes into the target box (e.g., `inside`, `cover`, `contain`, `fill`, `outside`).
     * Auto-format (WebP/AVIF): Leave enabled to let FlashEdge automatically serve WebP/AVIF to supported browsers. Toggle off only if you need to enforce original/specific formats.<br>
5. Click Enable Optimizer.

Saving starts a zone deployment. While the zone is deploying (status shows *"Applying changes…"*), Image Optimization is not yet active. Deployment usually completes within a minute or two.<br>

### Disable

1. Go to the Optimizer tab.
2. Click Disable or toggle off the Image Optimization switch. A confirmation dialog appears.
3. Confirm. Image Optimization is turned off; images are served directly from your origin without transformation.<br>

## How Automatic Formats Work

When a visitor requests an image without specifying a format, FlashEdge reads the browser's `Accept` header and picks the best option:<br>

| **Browser support**     | **Format served** |
| ----------------------- | ----------------- |
| AVIF supported          | AVIF              |
| No AVIF, WebP supported | WebP              |
| Neither supported       | JPEG              |

The same URL works across all browsers. Each format variant is generated once and then cached at the edge — subsequent requests for that variant are served directly from cache, no re-processing.<br>

{% hint style="info" %}
Tip: Only request a specific format (`?format=webp`) when you have a concrete reason. Letting FlashEdge choose automatically gives every visitor the smallest file their browser can display.
{% endhint %}

## URL Reference

### Query string parameters

Append parameters to any image URL on your FlashEdge zone:\
`[https://xyz.flashedgecdn.net/images/photo.jpg?width=400&quality=85](https://xyz.flashedgecdn.net/images/photo.jpg?width=400&quality=85)`<br>

| **Parameter** | **Alias** | **Description**                                                                    | **Default**                                                              |
| ------------- | --------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `width`       | `w`       | Target width in pixels. The image is resized to fit while preserving aspect ratio. | —                                                                        |
| `height`      | `h`       | Target height in pixels. Use with width or on its own.                             | —                                                                        |
| `fit`         | —         | How the image is resized when dimensions are set (see values below)                | <p><code>inside</code> (or <code>cover</code> if custom defined)<br></p> |
| `format`      | `f`       | Output format: `avif`, `webp`, or `jpeg`                                           | <p><code>auto</code> (browser-negotiated)<br></p>                        |
| `quality`     | `q`       | Output quality (1–100). Higher = bigger file.                                      | <p><code>80</code><br><br></p>                                           |

#### Accepted fit values

* `inside` *(Default in UI)*: Resize so the image fits inside the box. Like `contain`, but never adds padding — it only shrinks the image if larger.
* `cover`: Crop to cover the target area. The image fills the box; overflow is trimmed.
* `contain`: Letterbox. Fit the entire image inside the box, preserving aspect ratio, and fill the remaining space with a solid colour (or transparent for WebP/AVIF).
* `fill`: Stretch to fill the exact dimensions, ignoring aspect ratio.
* `outside`: Resize so at least one dimension equals the target. Like `contain` but never shrinks — it only enlarges if the image is smaller.<br>

### Pretty-URL form

Instead of query strings, you can embed resize parameters as path segments. The segment contains key=value pairs separated by commas, and can appear anywhere in the URL path:<br>

* `[https://xyz.flashedgecdn.net/images/width=400,format=webp/photo.jpg](https://xyz.flashedgecdn.net/images/width=400,format=webp/photo.jpg)`<br>
* `[https://xyz.flashedgecdn.net/width=400,quality=75/my/album/photo.jpg](https://xyz.flashedgecdn.net/width=400,quality=75/my/album/photo.jpg)`<br>

Allowed keys in pretty-URL segments: `width`, `height`, `fit`, `format`, `quality`, and the short aliases `w`, `h`, `q`, `f`. Any other key is ignored and the segment is passed through unchanged.\
Query string aliases also work (`w` → `width`, `h` → `height`, `q` → `quality`, `f` → `format`).<br>

#### Realistic examples

* Responsive thumbnail (query string):\
  `[https://xyz.flashedgecdn.net/products/hero.jpg?width=400](https://xyz.flashedgecdn.net/products/hero.jpg?width=400)`\
  *Browser gets AVIF or WebP at 400 px wide; cached for future visitors.*<br>
* Force WebP (for a legacy context):\
  `[https://xyz.flashedgecdn.net/blog/hero.jpg?format=webp&width=800](https://xyz.flashedgecdn.net/blog/hero.jpg?format=webp&width=800)`<br>
* Quality tuning (lower for thumbnails):\
  `[https://xyz.flashedgecdn.net/grid/tile.jpg?width=300&quality=75](https://xyz.flashedgecdn.net/grid/tile.jpg?width=300&quality=75)`<br>
* Pretty-URL equivalent:\
  `[https://xyz.flashedgecdn.net/width=300,quality=75/grid/tile.jpg](https://xyz.flashedgecdn.net/width=300,quality=75/grid/tile.jpg)`<br>

## Formats, Downgrades & Limits

* Automatic AVIF → WebP downgrade: AVIF images from an origin above 4 megapixels are automatically delivered as WebP. This keeps decode times fast on lower-powered devices. There is no user-facing indicator — the browser simply receives WebP.<br>
* Hard size ceiling (24 MP): Images from the origin exceeding 24 megapixels are always delivered as JPEG, regardless of format selection or browser support. This is a fixed ceiling.<br>
* Max input file size: Origin images larger than 25 MB return a `413 Payload Too Large` error and are not cached.<br>
* Missing or inaccessible source:
  * Source file not found → `404 Not Found`, cached for 60 seconds.
  * Source returns `403 Forbidden` → `403 Forbidden`, cached for 60 seconds.
  * Source server error (5xx) → `502 Bad Gateway`, not cached.<br>

## Caching & Regenerating Images

Each unique combination of source image, dimensions, fit mode, format, and quality produces one cached variant.<br>

* First request (slightly slower): When a new variant is requested for the first time, FlashEdge fetches the source image, transforms it, and streams the result. This adds a moment of latency compared to a cached response. All subsequent requests for that variant are served instantly from cache.<br>
* Regenerating after a source change: If you replace an image on your origin, the old cached variant is still served until it expires. To regenerate immediately:<br>
  1. Open your zone and go to the Optimizer tab.
  2. Click Save Changes — this does not change your settings but marks all image optimization variants for regeneration.
  3. Or, use Clear Cache from the zone header to invalidate specific image paths or all images at once.<br>

*Without Clear Cache, variants remain cached for up to a year. Always use it after updating source images if you need the new versions to be served right away.*<br>

## Best Practices

* Let the browser pick the format. Unless you have a specific reason, omit `format=`. The automatic AVIF/WebP/JPEG negotiation gives every visitor the smallest file their browser can display.
* Set Max Width / Width parameters to your layout width. Don't serve a 2000 px image to a 400 px slot. Use the preset Max width (px) field or URL parameters to match display size.
* Leverage Separate Mobile Presets. Enable mobile presets to automatically optimize images for mobile network constraints and screen sizes without needing custom client code.
* Quality 75–85 is usually the sweet spot. At quality 80 (the default), most images look near-indistinguishable from the original at roughly half the file size. Drop to 70–75 for thumbnails or decorative images where slight artefacts are imperceptible.
* Use pretty URLs for cleaner markup. Embedding `width=400,format=webp` directly in the image path keeps HTML templates readable and avoids query-string escaping issues.

&#x20;

***

### &#x20;<a href="#heading-h.uj5t8k6x29v" id="heading-h.uj5t8k6x29v"></a>