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)

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

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.

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

---

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

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, Presets, 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

---

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

---

Preset

pr:%preset_name1:%preset_name2:...

Wendet ein oder mehrere benannte Presets an, die serverseitig konfiguriert sind. Presets sind Sammlungen von Verarbeitungsoptionen, die über mehrere URLs hinweg wiederverwendet werden können. Operationen, die explizit in der URL gesetzt sind, überschreiben die Werte aus dem Preset.

Parameter	Typ	Standard	Erlaubte Werte
preset_nameN	string(s)	leer	Beliebige konfigurierte Preset-Namen

Beispiel:

# Ein einzelnes Preset anwenden
pr:thumbnail

# Mehrere Presets anwenden
pr:sharp:small