Ausgabe, Metadaten & Auslieferung

Diese Seite dokumentiert alle Operationen zur Steuerung von Ausgabeformat, Qualität, Metadaten und Auslieferungsverhalten.

Quality

q:%quality

Setzt die Ausgabequalität als Prozentwert. Gilt für verlustbehaftete Formate wie JPEG, WebP und AVIF. Bei 0 wird der serverseitige Standardwert verwendet.

Parameter	Typ	Standard	Erlaubte Werte
quality	integer	`0` (Server-Standard)	0-100

Beispiele:

# Hohe Qualität
q:95

# Gute Balance zwischen Qualität und Dateigröße
q:80

# Niedrige Qualität für Vorschauen
q:50

Format Quality

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

Setzt unterschiedliche Qualitätswerte pro Ausgabeformat. Nützlich, wenn Bilder in mehreren Formaten ausgeliefert werden und für jedes Format unterschiedliche Qualitätsstufen gewünscht sind.

Parameter	Typ	Standard	Erlaubte Werte
formatN	string	--	`jpeg`, `webp`, `avif`, `png` usw.
qualityN	integer	--	0-100

Format- und Qualitätswerte werden als abwechselnde Paare angegeben.

Beispiel:

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

Max Bytes

mb:%bytes

Begrenzt die Ausgabedateigröße, indem die Qualität automatisch reduziert wird, bis das Bild innerhalb der angegebenen Bytegrenze liegt. Funktioniert nur mit verlustbehafteten Formaten: JPEG, WebP, HEIC und TIFF.

Parameter	Typ	Standard	Erlaubte Werte
bytes	integer	`0` (deaktiviert)	Beliebige positive Ganzzahl (in Bytes)

WARNING

Wichtig: Wenn mb gesetzt ist, wird das Bild intern möglicherweise mehrfach gespeichert, um die Zielgröße zu erreichen. Das erhöht die Verarbeitungszeit.

Beispiele:

# Maximal 50 KB
mb:51200

# Maximal 100 KB
mb:102400

# Maximal 200 KB
mb:204800

Rewrite-Rule-Beispiel -- bandbreitenoptimierte Thumbnails:

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

Damit sind Thumbnails niemals größer als 20 KB, unabhängig vom Quellbild.

Format

f:%extension

Setzt das Ausgabeformat des Bildes. Wenn nicht angegeben, verwendet smoxy das Quellformat (Fallback: jpg).

Parameter	Typ	Standard	Erlaubte Werte
extension	string	Quellformat / `jpg`	`jpg`, `jpeg`, `png`, `webp`, `avif`, `gif`, `ico`, `heic`, `bmp`, `tiff`, `pdf`, `svg`

jpg und jpeg sind Aliase -- beide erzeugen JPEG-Ausgabe.

Beispiele:

# Zu WebP konvertieren
f:webp

# Zu AVIF konvertieren
f:avif

# Zu PNG konvertieren (verlustfrei)
f:png

Rewrite-Rule-Beispiel -- automatische WebP-Konvertierung:

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

WARNING

Wichtig: smoxy übernimmt bereits die automatische Formatkonvertierung (z. B. zu WebP oder AVIF) basierend auf den Fähigkeiten des Browsers. In den meisten Fällen ist es nicht nötig, das Format manuell zu setzen -- smoxy liefert automatisch das beste Format aus. Diese Option sollte nur verwendet werden, wenn ein bestimmtes Ausgabeformat unabhängig von der Browser-Unterstützung erzwungen werden soll.

Watermark

wmu:%encoded_url

Legt ein Wasserzeichen über das verarbeitete Bild. smoxy lädt das Wasserzeichen von der angegebenen URL, die base64url-kodiert übergeben wird. wmu allein schaltet das Wasserzeichen bereits ein: Ohne weitere Angaben sitzt es mittig, voll deckend und in Originalgröße. Deckkraft, Position und Größe lassen sich mit Watermark Placement anpassen.

Parameter	Typ	Standard	Erlaubte Werte
encoded_url	string	--	Absolute `http`- oder `https`-URL, base64url-kodiert ohne Padding

Wasserzeichen-URL kodieren

Kodiert wird mit dem URL-sicheren Base64-Alphabet und ohne Padding: Aus + wird -, aus / wird _, abschließende = entfallen. Standard-Base64 oder Werte mit Padding werden als ungültige Option abgelehnt.

bash

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

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

php

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

Aus https://www.example.com/static/watermark.png wird kodiert aHR0cHM6Ly93d3cuZXhhbXBsZS5jb20vc3RhdGljL3dhdGVybWFyay5wbmc.

Beispiel:

wmu:aHR0cHM6Ly93d3cuZXhhbXBsZS5jb20vc3RhdGljL3dhdGVybWFyay5wbmc

INFO

Tipps zum Wasserzeichen-Bild:

Am besten eignet sich ein PNG mit transparentem Hintergrund.
Die URL muss öffentlich erreichbar sein und einen Hostnamen enthalten, keine IP-Adresse.
Das Wasserzeichen wird für jedes verarbeitete Bild neu geladen, das noch nicht im Cache liegt. Liegt es auf einem Hostnamen der Zone, kommt es dabei aus dem smoxy-Cache.

WARNING

Wichtig:

Lässt sich das Wasserzeichen nicht laden, schlägt die Bildanfrage fehl. Eine Auslieferung ohne Wasserzeichen als Ersatz gibt es nicht. Ist die Wasserzeichen-URL fehlerhaft, wird also keines der Bilder mehr ausgeliefert, auf die die Regel greift.
Die URL des Wasserzeichens darf nicht selbst auf die Rewrite Rule passen, die das Wasserzeichen hinzufügt. Sonst durchläuft schon das Laden des Wasserzeichens dieselbe Regel.

Watermark Placement

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

Steuert Deckkraft, Position und Größe des Wasserzeichens. wm wirkt nur zusammen mit wmu, für sich allein erzeugt es kein Wasserzeichen. In welcher Reihenfolge die beiden Optionen in der URL stehen, spielt keine Rolle.

Parameter	Typ	Standard	Erlaubte Werte
opacity	float	--	0-1. Bei `0` ist das Wasserzeichen unsichtbar
position	string	`ce`	Siehe Tabelle unten
x_offset	float	`0`	Absolute Pixel (>= 1) oder relativ (< 1)
y_offset	float	`0`	Absolute Pixel (>= 1) oder relativ (< 1)
scale	float	`0`	Jeder Wert >= 0. `0` behält die Originalgröße bei

opacity ist Pflicht, alle weiteren Parameter sind optional.

Wasserzeichen-Positionen

Wert	Position
`ce`	Mitte (Standard)
`no`	Norden -- oberer Rand
`so`	Süden -- unterer Rand
`ea`	Osten -- rechter Rand
`we`	Westen -- linker Rand
`noea`	Nordost -- obere rechte Ecke
`nowe`	Nordwest -- obere linke Ecke
`soea`	Südost -- untere rechte Ecke
`sowe`	Südwest -- untere linke Ecke
`re`	Wiederholen -- Wasserzeichen über das ganze Bild kacheln

Bei Rand- und Eckpositionen geben die Offsets den Abstand zum Rand an, bei re den Abstand zwischen den Kacheln. Relative Werte (< 1) beziehen sich auf die Breite bzw. Höhe des Bildes.

scale bestimmt die Größe des Wasserzeichens im Verhältnis zum Ausgabebild: Es wird so verkleinert oder vergrößert, dass es in diesen Anteil von Bildbreite und Bildhöhe passt. Bei 0.2 nimmt es höchstens 20 % der Breite und 20 % der Höhe ein.

Beispiele:

# 50 % Deckkraft, mittig
wm:0.5

# Untere rechte Ecke, 20 px Abstand zu den Rändern, höchstens 20 % der Bildgröße
wm:0.5:soea:20:20:0.2

# Über das ganze Bild gekachelt, 100 px zwischen den Kacheln, 30 % Deckkraft
wm:0.3:re:100:100

Rewrite-Rule-Beispiel -- Wasserzeichen auf Produktbildern:

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

Damit sitzt das Wasserzeichen von https://www.example.com/static/watermark.png in der unteren rechten Ecke: 50 % Deckkraft, 20 px Abstand zu den Rändern, höchstens 20 % von Bildbreite und Bildhöhe. Das Wasserzeichen selbst liegt unter /static/, die Regel greift also nicht darauf.

INFO

Hinweis: Das Wasserzeichen wird als letzter Schritt aufgebracht, nach dem Padding. Seine Position bezieht sich deshalb auf die endgültigen Bildmaße. Pixel-Offsets skalieren mit DPR, nicht aber mit Zoom.

WARNING

Wasserzeichen ändern: Verarbeitete Bilder werden unter der aufgerufenen URL gecacht, nicht unter dem Ziel der Rewrite Rule. Weder ein ausgetauschtes Wasserzeichen-Bild noch eine geänderte Wasserzeichen-URL in der Regel wirkt sich auf Bilder aus, die bereits im Cache liegen. Nach einer Änderung deshalb die gecachten Bilder invalidieren, etwa per Flush Content Class mit type: images.

Strip Metadata

sm:%strip_metadata

Steuert, ob EXIF-, IPTC-, XMP- und andere Metadaten aus dem Ergebnisbild entfernt werden.

Parameter	Typ	Standard	Erlaubte Werte
strip_metadata	boolean	Server-Standard	`1`, `t`, `true` zum Entfernen; `0`, `f`, `false` zum Beibehalten

Beispiele:

# Alle Metadaten entfernen
sm:1

# Metadaten beibehalten
sm:0

Keep Copyright

kcr:%keep_copyright

Bewahrt Copyright-bezogene Metadaten auch dann, wenn das Entfernen von Metadaten aktiviert ist. Hat nur Wirkung, wenn sm:1 (Strip Metadata) aktiv ist.

Parameter	Typ	Standard	Erlaubte Werte
keep_copyright	boolean	Server-Standard	`1`, `t`, `true` zum Beibehalten; `0`, `f`, `false` zum Entfernen

Beispiel:

# Metadaten entfernen, aber Copyright-Infos beibehalten
sm:1/kcr:1

Strip Color Profile

scp:%strip_color_profile

Steuert, ob das eingebettete ICC-Farbprofil in sRGB umgewandelt und entfernt wird. Das hilft, die Dateigröße zu reduzieren und gleichzeitig konsistente Farben auf verschiedenen Geräten sicherzustellen.

Parameter	Typ	Standard	Erlaubte Werte
strip_color_profile	boolean	Server-Standard	`1`, `t`, `true` zum Entfernen; `0`, `f`, `false` zum Beibehalten

Beispiel:

# Farbprofil entfernen
scp:1

Enforce Thumbnail

eth:%enforce_thumbnail

Wenn aktiviert, wird die Verwendung eines eingebetteten Thumbnails anstelle des Hauptbildes erzwungen. Unterstützt derzeit nur Thumbnails in HEIC- und AVIF-Formaten.

Parameter	Typ	Standard	Erlaubte Werte
enforce_thumbnail	boolean	`false`	`1`, `t`, `true` zum Aktivieren; `0`, `f`, `false` zum Deaktivieren

Beispiel:

eth:1

Skip Processing

skp:%extension1:%extension2:...

Überspringt die gesamte Verarbeitung für Bilder in den angegebenen Formaten. Das Bild wird unverändert zurückgegeben. Funktioniert nur, wenn das angeforderte Ausgabeformat mit dem Quellformat übereinstimmt.

Parameter	Typ	Standard	Erlaubte Werte
extensionN	string(s)	leer	Beliebige Format-Endungen: `svg`, `gif`, `png` usw.

Beispiele:

# Verarbeitung für SVG und GIF überspringen
skp:svg:gif

# Verarbeitung für PNG überspringen
skp:png

Raw

raw:%raw

Gibt die rohe, unverarbeitete Quelldatei direkt zurück. Alle Verarbeitungsoperationen und Prüfungen (Typ, Auflösung, Dateigröße) werden übersprungen. Die Datei wird direkt gestreamt, was weniger Arbeitsspeicher als die normale Verarbeitung benötigt.

Parameter	Typ	Standard	Erlaubte Werte
raw	boolean	`false`	`1`, `t`, `true` zum Aktivieren; `0`, `f`, `false` zum Deaktivieren

INFO

Tipp: Im Gegensatz zu skp funktioniert die raw-Option mit jedem Dateityp und führt keinerlei Prüfung des Quellbildes durch. Ideal, wenn Dateien unverändert über die Bildmanipulations-Pipeline ausgeliefert werden sollen.

Beispiel:

raw:1

Cache Buster

cb:%string

Hat keinen Einfluss auf die Bildverarbeitung. Der einzige Zweck ist, die URL zu verändern, damit CDN-, Proxy- und Browser-Caches umgangen werden. Nützlich, wenn serverseitige Einstellungen (Qualität, Wasserzeichen) geändert wurden, die sich nicht in der URL widerspiegeln.

Parameter	Typ	Standard	Erlaubte Werte
string	string	leer	Beliebiger String

Beispiele:

# Versionsbasiertes Cache-Busting
cb:v2

# Datumsbasiertes Cache-Busting
cb:20250226

INFO

Hinweis: Wie smoxy den Cache-Key für verarbeitete Bilder bildet -- und wie sich dieser über Query-Strings, Hosts und Sprachen hinweg normalisieren lässt -- beschreibt Cache-Key-Konfiguration für Bilder.

Expires

exp:%timestamp

Setzt einen Unix-Zeitstempel, nach dem die URL ungültig wird. smoxy gibt einen 404-Fehler für abgelaufene URLs zurück. Nützlich für zeitlich begrenzten Bildzugriff.

Parameter	Typ	Standard	Erlaubte Werte
timestamp	integer	leer (kein Ablauf)	Unix-Zeitstempel

Beispiel:

# Läuft am 1. Januar 2026 ab
exp:1767225600

Filename

fn:%filename:%encoded

Setzt den Dateinamen, der im Content-Disposition-Response-Header verwendet wird. Wenn nicht angegeben, leitet smoxy den Dateinamen aus der Quell-URL ab.

Parameter	Typ	Standard	Erlaubte Werte
filename	string	Dateiname der Quell-URL	Escaped String oder URL-safe Base64-kodierter String
encoded	boolean	`false`	`1`, `t`, `true` wenn der Dateiname Base64-kodiert ist

Beispiel:

fn:produkt-foto.jpg

Return Attachment

att:%return_attachment

Wenn aktiviert, wird der Content-Disposition-Header auf attachment gesetzt. Dadurch wird im Browser ein „Speichern unter"-Dialog ausgelöst, anstatt das Bild direkt anzuzeigen.

Parameter	Typ	Standard	Erlaubte Werte
return_attachment	boolean	`false`	`1`, `t`, `true` zum Aktivieren; `0`, `f`, `false` zum Deaktivieren

Beispiel:

# Download erzwingen
att:1

Rewrite-Rule-Beispiel -- herunterladbare Bilder:

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

Ausgabe, Metadaten & Auslieferung ​

Quality ​

Format Quality ​

Max Bytes ​

Format ​

Watermark ​

Wasserzeichen-URL kodieren ​

Watermark Placement ​

Wasserzeichen-Positionen ​

Strip Metadata ​

Keep Copyright ​

Strip Color Profile ​

Enforce Thumbnail ​

Skip Processing ​

Raw ​

Cache Buster ​

Expires ​

Filename ​

Return Attachment ​

Ausgabe, Metadaten & Auslieferung

Quality

Format Quality

Max Bytes

Format

Watermark

Wasserzeichen-URL kodieren

Watermark Placement

Wasserzeichen-Positionen

Strip Metadata

Keep Copyright

Strip Color Profile

Enforce Thumbnail

Skip Processing

Raw

Cache Buster

Expires

Filename

Return Attachment