Snapkit Logo

Image Transform API#

Verwenden Sie Snapkits Image Transform API, um Echtzeitbildtransformationen über URL-Parameter durchzuführen. Basierend auf der Sharp↗-Bibliothek für Hochleistungsverarbeitung und CloudFront CDN bietet es weltweit schnelle Bildauslieferung.

Schnellstart#

Grundlegende Verwendung#

Fügen Sie Abfrageparameter zu hochgeladenen Bild-URLs für Echtzeittransformation hinzu:

GET https://{organization}-cdn.snapkit.studio
  /{project}
  /{path}
  /{filename}
  ?w=800&h=600&fit=cover&flip=true&grayscale=true&dpr=2

URL-Komponenten:

  • {organization}: Organisationsname (z.B. acme-corp)
  • {project}: Projektname
  • {path}: Ordnerpfad
  • {filename}: Bilddateiname
  • Abfrageparameter: Transformationsoptionen (w, h, fit, etc.)

Hauptfunktionen#

  • Echtzeittransformation: Sofortige Bildtransformation über URL-Parameter
  • CDN-Zwischenspeicherung: Schnelle Bildauslieferung von CloudFront nach der ersten Transformation
  • Automatische Optimierung: Automatische Formatwahl basierend auf Browserfähigkeiten
  • High-Resolution-Unterstützung: Responsive Bilderzeugung basierend auf DPR (Device Pixel Ratio)

Transformationsparameter-Referenz#

Größe & Layout#

Parameter

Typ

Beschreibung

Standard

Grenzen

w

number

Breite (Pixel)

Max 4.096px

h

number

Höhe (Pixel)

Max 4.096px

fit

string

Anpassungsmodus: contain, cover, fill , inside, outside

cover
dpr

number

Device Pixel Ratio

1.0

1.0-4.0

Transformation & Effekte#

Parameter

Typ

Beschreibung

Grenzen

rotation

number

Rotationswinkel (0-360 Grad, auto-normalisiert)

flip

boolean

Vertikale Spiegelung

flop

boolean

Horizontale Spiegelung

blur

number

Unschärfeintensität

Max 20

grayscale

boolean

In Graustufen konvertieren

Bereich & Format#

Parameter

Typ

Beschreibung

Grenzen

extract

string

Bereich extrahieren: x,y,width,height Format

Max 4.096x4.096

format

string

Ausgabeformat: jpeg, jpg, png, webp, avif, auto

Praktische Anwendungsbeispiele#

Responsive Bildoptimierung#

High-Resolution für Desktop

?w=800&h=600&dpr=2.0&format=webp&fit=cover

Mobile Optimierung

?w=375&dpr=3&format=auto&fit=cover

Thumbnail-Generierung

?w=200&h=200&fit=cover

Erweiterte Transformationskombinationen#

Portfolio-Galerie

?w=400&h=300&grayscale=true&blur=1&format=webp

Produktbilder

?w=600&h=600&fit=contain&format=auto

Bildvorschau

?extract=25,25,50,50&w=300&format=jpeg

Grundlegende Transformationsoptionen#

Größe ändern

?w=800&h=600&fit=cover

Drehen und spiegeln

?rotation=90&flip=true

Unschärfe- und Graustufen-Effekte

?blur=2&grayscale=true
Originalbild
Original

Größe angepasst (w=300&h=200&fit=cover)

Resized

Transformationseffekte-Visualisierung#

Originalbild
Original

Größe ändern + High-Resolution (w=300&h=200&fit=cover&dpr=2.0)

Resized with DPR
Original
Original
Graustufen-Konvertierung
Grayscale
Unschärfe-Effekt
Blurred
Original
Original
Unschärfe angewendet (blur=5)
Blurred
Rotationseffekt (rotation=15)
Rotated

Device Pixel Ratio (DPR) Verwendung#

Passen Sie die tatsächliche Bildgröße für High-Resolution-Display-Unterstützung an. Berechnen Sie die tatsächliche Bildgröße, indem Sie die angegebene Größe mit dem DPR-Wert multiplizieren.

Wie DPR funktioniert#

  • w=300&dpr=1.0 → Tatsächliche Bildgröße: 300px (300 × 1.0)
  • w=300&dpr=1.5 → Tatsächliche Bildgröße: 450px (300 × 1.5)
  • w=300&dpr=2.0 → Tatsächliche Bildgröße: 600px (300 × 2.0)

Der Browser zeigt immer noch in der angegebenen Größe (300px) an, lädt aber ein größeres Bild für scharfe Darstellung herunter.

DPR 1.0 (tatsächlich 300px)
DPR 1.0
DPR 1.5 (tatsächlich 450px)
DPR 1.5
DPR 2.0 (tatsächlich 600px)
DPR 2.0

Verwendungsbeispiele#

Desktop Standard-Auflösung

?w=400&h=300&dpr=2

Hochauflösende Retina Mobile

?w=400&h=300&dpr=3

Transformationsverarbeitungsreihenfolge#

Bildtransformationen werden in folgender Reihenfolge verarbeitet:

  1. Resize (Größenanpassung) - DPR angewendet
  2. Rotation (Rotation)
  3. Flip/Flop (Spiegelung)
  4. Blur (Unschärfe-Effekt)
  5. Grayscale (Graustufen-Konvertierung)
  6. Extract (Bereichsextraktion)
  7. Format (Formatkonvertierung)

Komplexe Transformationsbeispiele#

Sie können mehrere Transformationen kombinieren:

Größenanpassung + Graustufen + Unschärfe

?w=400&h=300&grayscale=true&blur=2

Bereichsextraktion + Rotation

?extract=25,25,50,50&rotation=90

High-Resolution-Display-Optimierung

?w=400&h=300&dpr=2.0&format=webp

Mobile responsive Bilder

?w=375&dpr=1.5&format=auto&fit=cover

Rotation und Spiegelung kombiniert

?rotation=45&flip=true&blur=1

Leistung & Zwischenspeicherung#

CloudFront CDN#

Alle transformierten Bilder werden auf CloudFront CDN zwischengespeichert für schnelle Auslieferung:

  • Erste Anfrage: Originalbild transformieren und zwischenspeichern
  • Nachfolgende Anfragen: Sofortige Auslieferung aus dem Cache
  • Cache-Dauer: 1 Jahr

Accept Header-basierte Optimierung#

Wenn der format-Parameter auto ist, wird das optimale Format automatisch basierend auf dem Accept-Header des Browsers ausgewählt:

  • AVIF-unterstützende Browser: Konvertierung zu AVIF-Format
  • WebP-unterstützende Browser: Konvertierung zu WebP-Format
  • Standard-Browser: Konvertierung zu JPEG/PNG-Format

Systembeschränkungen & Schutzmaßnahmen#

Verarbeitungsbeschränkungen#

  • Maximale Bildgröße: 4.096 x 4.096 Pixel
  • Eingabepixel-Limit: 268.402.689 Pixel (ungefähr 16K x 16K)
  • Unschärfe-Intensität: Maximum 20 (CPU-Schutz)
  • DPR-Bereich: 1.0-4.0

Automatisches Fallback-System#

Automatische Behandlung bei Problemen während der Transformation:

  1. Parameterfehler: Automatische Korrektur ungültiger Werte
  2. Transformationsfehler: Rückgabe des Originalbildes
  3. Speichermangel: Verarbeitungsbeschränkungen gewährleisten Systemsicherheit
  4. Formatfehler: Konvertierung zu Standard-JPEG-Format

Speicheroptimierung#

  • Cache deaktiviert: Sharp-Speicher-Cache nicht verwendet
  • Automatische Bereinigung: Automatische Freigabe von Sharp-Bibliotheksinstanzen nach Verarbeitungsabschluss
  • Einzelverarbeitung: Nebenläufigkeit zum Speicherschutz begrenzt

Integration & Verwendung#

Next.js Integration (Demnächst)#

Derzeit in Entwicklung. Demnächst verfügbar.

Bleiben Sie auf dem Laufenden:

import { Image } from "@snapkit/nextjs";
 
<Image
  src="https://{organization}-<your-org>-cdn.snapkit.studio/{project}/images/hero.jpg"
  alt="Hero"
  width={800}
  height={600}
  transforms={{
    blur: 0,
    format: "auto",
    dpr: 2.0,
  }}
/>;

Responsive Bildimplementierung#

const getResponsiveUrl = (src: string, width: number, mobile = false) => {
  const dpr = mobile ? 1.5 : 3.0;
  return `${src}?w=${width}&dpr=${dpr}&fit=cover&format=auto`;
};
 
// Verwendungsbeispiel
<picture>
  <source media="(min-width: 768px)" srcSet={getResponsiveUrl(baseUrl, 800)} />
  <img src={getResponsiveUrl(baseUrl, 400, true)} alt="Responsive" />
</picture>;

Nächste Schritte#