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

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.

---

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, presets, watermarks) 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

---

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

---

Preset

pr:%preset_name1:%preset_name2:...

Applies one or more named presets that are configured on the server side. Presets are collections of processing options that can be reused across multiple URLs. Operations set explicitly in the URL override the values from the preset.

Parameter	Type	Default	Allowed Values
preset_nameN	string(s)	empty	Any configured preset name(s)

Example:

# Apply a single preset
pr:thumbnail

# Apply multiple presets
pr:sharp:small