---
url: https://docs.smoxy.eu/image-processing/output-metadata-and-delivery.md
---
# Output, Metadata & Delivery

This page documents all operations for controlling output format, quality, metadata handling, and delivery behavior.

### Quality

```
q:%quality
```

Sets the output quality as a percentage. Applies to lossy formats like JPEG, WebP, and AVIF. When set to `0`, the quality falls back to the server-side default.

| Parameter | Type    | Default              | Allowed Values |
| --------- | ------- | -------------------- | -------------- |
| quality   | integer | `0` (server default) | 0-100          |

**Examples:**

```
# High quality
q:95

# Good balance of quality and file size
q:80

# Low quality for previews
q:50
```

***

### Format Quality

```
fq:%format1:%quality1:%format2:%quality2:...
```

Sets different quality values per output format. This is useful when you serve images in multiple formats and want different quality levels for each.

| Parameter | Type    | Default | Allowed Values                      |
| --------- | ------- | ------- | ----------------------------------- |
| formatN   | string  | --      | `jpeg`, `webp`, `avif`, `png`, etc. |
| qualityN  | integer | --      | 0-100                               |

The format and quality values are provided as alternating pairs.

**Example:**

```
# JPEG at 80%, WebP at 75%, AVIF at 60%
fq:jpeg:80:webp:75:avif:60
```

***

### Max Bytes

```
mb:%bytes
```

Limits the output file size by automatically reducing quality until the image fits within the specified byte limit. Only works with lossy formats: JPEG, WebP, HEIC, and TIFF.

| Parameter | Type    | Default        | Allowed Values                  |
| --------- | ------- | -------------- | ------------------------------- |
| bytes     | integer | `0` (disabled) | Any positive integer (in bytes) |

::: warning
**Important:** When `mb` is set, the image may be saved multiple times internally to reach the target size. This increases processing time.
:::

**Examples:**

```
# Max 50 KB
mb:51200

# Max 100 KB
mb:102400

# Max 200 KB
mb:204800
```

**Rewrite rule example -- bandwidth-optimized thumbnails:**

Regex: `^/small/(.*)` Target: `/_sx/img/_/rs:fit:200:200/mb:20480/plain/$1`

This ensures thumbnails are never larger than 20 KB, regardless of the source image.

***

### Format

```
f:%extension
```

Sets the output image format. If not specified, smoxy uses the source format (falling back to `jpg`).

| Parameter | Type   | Default               | Allowed Values                                                                          |
| --------- | ------ | --------------------- | --------------------------------------------------------------------------------------- |
| extension | string | source format / `jpg` | `jpg`, `jpeg`, `png`, `webp`, `avif`, `gif`, `ico`, `heic`, `bmp`, `tiff`, `pdf`, `svg` |

`jpg` and `jpeg` are aliases -- both produce JPEG output.

**Examples:**

```
# Convert to WebP
f:webp

# Convert to AVIF
f:avif

# Convert to PNG (lossless)
f:png
```

**Rewrite rule example -- automatic WebP conversion:**

Regex: `^/webp/(.*)` Target: `/_sx/img/_/f:webp/q:80/plain/$1`

::: warning
**Important:** smoxy already handles automatic format conversion (e.g., to WebP or AVIF) based on what the browser supports. In most cases, you do **not** need to set the format manually -- smoxy will serve the best format automatically. Only use this option when you need to enforce a specific output format regardless of browser support.
:::

***

### Watermark

```
wmu:%encoded_url
```

Places a watermark image on top of the processed image. smoxy loads the watermark from the given URL, which is passed base64url-encoded. Setting `wmu` is enough to turn the watermark on: without further options, it's placed in the center at full opacity and in its original size. Use [Watermark Placement](#watermark-placement) to change opacity, position, and size.

| Parameter    | Type   | Default | Allowed Values                                                |
| ------------ | ------ | ------- | ------------------------------------------------------------- |
| encoded\_url | string | --      | Absolute `http` or `https` URL, base64url-encoded without padding |

#### Encoding the watermark URL

The URL is encoded with the URL-safe base64 alphabet and without padding: `+` becomes `-`, `/` becomes `_`, and trailing `=` characters are removed. Standard or padded base64 is rejected as an invalid option.

```bash
# Shell
printf %s 'https://www.example.com/static/watermark.png' | base64 | tr '+/' '-_' | tr -d '=\n'
```

```js
// JavaScript
btoa(url).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
```

```php
// PHP
rtrim(strtr(base64_encode($url), '+/', '-_'), '=')
```

`https://www.example.com/static/watermark.png` encodes to `aHR0cHM6Ly93d3cuZXhhbXBsZS5jb20vc3RhdGljL3dhdGVybWFyay5wbmc`.

**Example:**

```
wmu:aHR0cHM6Ly93d3cuZXhhbXBsZS5jb20vc3RhdGljL3dhdGVybWFyay5wbmc
```

::: info
**Tips for the watermark image:**

* Use a PNG with a transparent background.
* The URL must be publicly reachable and use a hostname, not an IP address.
* The watermark is loaded again for every processed image that isn't cached yet. Host it on one of the zone's own hostnames so it's delivered from smoxy's cache.
  :::

::: warning
**Important:**

* If the watermark can't be loaded, the image request fails. smoxy doesn't fall back to the image without a watermark, so a broken watermark URL breaks every image the rule applies to.
* The watermark's own URL must not match the rewrite rule that adds the watermark. Otherwise, loading the watermark runs through the same rule again.
  :::

***

### Watermark Placement

```
wm:%opacity:%position:%x_offset:%y_offset:%scale
```

Controls opacity, position, and size of the [watermark](#watermark). `wm` only takes effect together with `wmu`; on its own, it doesn't add a watermark. The two options can appear in any order.

| Parameter | Type   | Default | Allowed Values                              |
| --------- | ------ | ------- | ------------------------------------------- |
| opacity   | float  | --      | 0-1. `0` hides the watermark                |
| position  | string | `ce`    | See table below                             |
| x\_offset | float  | `0`     | Absolute pixels (>= 1) or relative (< 1)    |
| y\_offset | float  | `0`     | Absolute pixels (>= 1) or relative (< 1)    |
| scale     | float  | `0`     | Any value >= 0. `0` keeps the original size |

`opacity` is required; all other parameters are optional.

#### Watermark positions

| Value  | Position                                       |
| ------ | ---------------------------------------------- |
| `ce`   | Center (default)                               |
| `no`   | North -- top edge                              |
| `so`   | South -- bottom edge                           |
| `ea`   | East -- right edge                             |
| `we`   | West -- left edge                              |
| `noea` | North-east -- top-right corner                 |
| `nowe` | North-west -- top-left corner                  |
| `soea` | South-east -- bottom-right corner              |
| `sowe` | South-west -- bottom-left corner               |
| `re`   | Repeat -- tiles the watermark across the image |

For edge and corner positions, the offsets set the distance from the edges. With `re`, they set the spacing between the tiles. Relative values (< 1) are a fraction of the image width or height.

`scale` sets the watermark size relative to the output image: the watermark is resized, up or down, to fit within that share of the image's width and height. With `0.2`, it takes up at most 20% of the width and 20% of the height.

**Examples:**

```
# 50% opacity, centered
wm:0.5

# Bottom-right corner, 20 px from the edges, at most 20% of the image size
wm:0.5:soea:20:20:0.2

# Tiled across the image, 100 px between tiles, 30% opacity
wm:0.3:re:100:100
```

**Rewrite rule example -- watermark on product images:**

Regex: `^/media/(.*\.(?:jpe?g|png|webp))$` Target: `/_sx/img/_/wm:0.5:soea:20:20:0.2/wmu:aHR0cHM6Ly93d3cuZXhhbXBsZS5jb20vc3RhdGljL3dhdGVybWFyay5wbmc/plain/media/$1`

This places the watermark from `https://www.example.com/static/watermark.png` in the bottom-right corner: 50% opacity, 20 px from the edges, at most 20% of the image's width and height. The watermark itself lives under `/static/`, so the rule doesn't apply to it.

::: info
**Note:** The watermark is applied last, after [padding](/image-processing/effects-and-adjustments#padding), so its position refers to the final image dimensions. Pixel offsets scale with [DPR](/image-processing/resizing-and-cropping#dpr-device-pixel-ratio), but not with [zoom](/image-processing/resizing-and-cropping#zoom).
:::

::: warning
**Changing the watermark:** Processed images are cached under the requested URL, not under the rewrite target. Neither replacing the watermark file nor changing the watermark URL in the rule updates images that are already cached. After a change, clear the cached images, for example with a [content-class purge](/developer-guide/cache-invalidation#flush-content-class) using `type: images`.
:::

***

### Strip Metadata

```
sm:%strip_metadata
```

Controls whether EXIF, IPTC, XMP, and other metadata is stripped from the output image.

| Parameter       | Type    | Default        | Allowed Values                                       |
| --------------- | ------- | -------------- | ---------------------------------------------------- |
| strip\_metadata | boolean | server default | `1`, `t`, `true` to strip; `0`, `f`, `false` to keep |

**Examples:**

```
# Strip all metadata
sm:1

# Keep metadata
sm:0
```

***

### Keep Copyright

```
kcr:%keep_copyright
```

Preserves copyright-related metadata even when metadata stripping is enabled. Only has an effect when `sm:1` (strip metadata) is active.

| Parameter       | Type    | Default        | Allowed Values                                       |
| --------------- | ------- | -------------- | ---------------------------------------------------- |
| keep\_copyright | boolean | server default | `1`, `t`, `true` to keep; `0`, `f`, `false` to strip |

**Example:**

```
# Strip metadata but keep copyright info
sm:1/kcr:1
```

***

### Strip Color Profile

```
scp:%strip_color_profile
```

Controls whether the embedded ICC color profile is transformed to sRGB and removed. This helps reduce file size while maintaining consistent colors across devices.

| Parameter             | Type    | Default        | Allowed Values                                       |
| --------------------- | ------- | -------------- | ---------------------------------------------------- |
| strip\_color\_profile | boolean | server default | `1`, `t`, `true` to strip; `0`, `f`, `false` to keep |

**Example:**

```
# Strip color profile
scp:1
```

***

### Enforce Thumbnail

```
eth:%enforce_thumbnail
```

When enabled, forces the use of an embedded thumbnail instead of the main image. Currently supports thumbnails embedded in HEIC and AVIF formats only.

| Parameter          | Type    | Default | Allowed Values                                           |
| ------------------ | ------- | ------- | -------------------------------------------------------- |
| enforce\_thumbnail | boolean | `false` | `1`, `t`, `true` to enable; `0`, `f`, `false` to disable |

**Example:**

```
eth:1
```

***

### Skip Processing

```
skp:%extension1:%extension2:...
```

Skips all processing for images that match the listed formats. The image is returned as-is. This only works when the requested output format matches the source format.

| Parameter  | Type      | Default | Allowed Values                                     |
| ---------- | --------- | ------- | -------------------------------------------------- |
| extensionN | string(s) | empty   | Any format extension(s): `svg`, `gif`, `png`, etc. |

**Examples:**

```
# Skip processing for SVG and GIF files
skp:svg:gif

# Skip processing for PNG files
skp:png
```

***

### Raw

```
raw:%raw
```

Returns the raw, unprocessed source file directly. All processing operations and checks (type, resolution, file size) are skipped. The file is streamed directly, using less memory than normal processing.

| Parameter | Type    | Default | Allowed Values                                           |
| --------- | ------- | ------- | -------------------------------------------------------- |
| raw       | boolean | `false` | `1`, `t`, `true` to enable; `0`, `f`, `false` to disable |

::: info
**Tip:** Unlike `skp`, the `raw` option works with any file type and doesn't check the source image at all. Use this when you need to serve files as-is through the image manipulation pipeline.
:::

**Example:**

```
raw:1
```

***

### Cache Buster

```
cb:%string
```

Does not affect image processing. Its sole purpose is to change the URL so that CDN, proxy, and browser caches are bypassed. Use this when you've changed server-side settings (quality, [watermarks](#watermark)) that aren't reflected in the URL itself.

| Parameter | Type   | Default | Allowed Values       |
| --------- | ------ | ------- | -------------------- |
| string    | string | empty   | Any arbitrary string |

**Examples:**

```
# Version-based cache busting
cb:v2

# Date-based cache busting
cb:20250226
```

::: info
**Note:** For how smoxy builds the cache key for processed images -- and how to normalize it across query strings, hosts, and languages -- see [Cache key configuration for images](/developer-guide/cache-key-configuration-for-images).
:::

***

### Expires

```
exp:%timestamp
```

Sets a Unix timestamp after which the URL becomes invalid. smoxy returns a 404 error for expired URLs. This is useful for time-limited image access.

| Parameter | Type    | Default           | Allowed Values |
| --------- | ------- | ----------------- | -------------- |
| timestamp | integer | empty (no expiry) | Unix timestamp |

**Example:**

```
# Expires on January 1, 2026
exp:1767225600
```

***

### Filename

```
fn:%filename:%encoded
```

Sets the filename used in the `Content-Disposition` response header. When not specified, smoxy derives the filename from the source URL.

| Parameter | Type    | Default             | Allowed Values                                     |
| --------- | ------- | ------------------- | -------------------------------------------------- |
| filename  | string  | source URL filename | Escaped string or URL-safe Base64-encoded string   |
| encoded   | boolean | `false`             | `1`, `t`, `true` if the filename is Base64-encoded |

**Example:**

```
fn:product-photo.jpg
```

***

### Return Attachment

```
att:%return_attachment
```

When enabled, sets the `Content-Disposition` header to `attachment`, which triggers a "Save As" dialog in the browser instead of displaying the image.

| Parameter          | Type    | Default | Allowed Values                                           |
| ------------------ | ------- | ------- | -------------------------------------------------------- |
| return\_attachment | boolean | `false` | `1`, `t`, `true` to enable; `0`, `f`, `false` to disable |

**Example:**

```
# Force download
att:1
```

**Rewrite rule example -- downloadable images:**

Regex: `^/download/(.*)` Target: `/_sx/img/_/att:1/fn:download/plain/$1`
