Snapkit Logo

API de Transformation d'Images#

Utilisez l'API de Transformation d'Images de Snapkit pour effectuer des transformations d'images en temps réel via des paramètres URL. Basée sur la bibliothèque Sharp↗ pour un traitement haute performance et CloudFront CDN, elle offre une livraison d'images rapide dans le monde entier.

Démarrage Rapide#

Utilisation de Base#

Ajoutez des paramètres de requête aux URLs d'images téléchargées pour une transformation en temps réel :

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

Composants d'URL :

  • {organization} : Nom de l'organisation (ex. acme-corp)
  • {project} : Nom du projet
  • {path} : Chemin du dossier
  • {filename} : Nom du fichier image
  • Paramètres de requête : Options de transformation (w, h, fit, etc.)

Fonctionnalités Clés#

  • Transformation en temps réel : Transformation instantanée d'images via paramètres URL
  • Cache CDN : Livraison rapide d'images depuis CloudFront après la première transformation
  • Optimisation automatique : Sélection automatique de format basée sur les capacités du navigateur
  • Support haute résolution : Génération d'images responsives basée sur DPR (Device Pixel Ratio)

Référence des Paramètres de Transformation#

Taille et Disposition#

Paramètre

Type

Description

Par Défaut

Limites

w

number

Largeur (pixels)

Max 4 096px

h

number

Hauteur (pixels)

Max 4 096px

fit

string

Mode d'ajustement : contain, cover, fill , inside, outside

cover
dpr

number

Device Pixel Ratio

1.0

1.0-4.0

Transformation et Effets#

Paramètre

Type

Description

Limites

rotation

number

Angle de rotation (0-360 degrés, auto-normalisé)

flip

boolean

Retournement vertical

flop

boolean

Retournement horizontal

blur

number

Intensité du flou

Max 20

grayscale

boolean

Conversion en niveaux de gris

Région et Format#

Paramètre

Type

Description

Limites

extract

string

Extraire une région : format x,y,width,height

Max 4 096x4 096

format

string

Format de sortie : jpeg, jpg, png, webp, avif, auto

Exemples d'Utilisation Pratique#

Optimisation d'Images Responsives#

Haute résolution pour desktop

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

Optimisation mobile

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

Génération de vignettes

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

Combinaisons Avancées de Transformation#

Galerie de portfolio

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

Images de produits

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

Aperçu d'image

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

Options de Transformation de Base#

Redimensionner

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

Rotation et retournement

?rotation=90&flip=true

Effets de flou et niveaux de gris

?blur=2&grayscale=true
Image originale
Original

Redimensionnement appliqué (w=300&h=200&fit=cover)

Resized

Visualisation des Effets de Transformation#

Image originale
Original

Redimensionner + Haute résolution (w=300&h=200&fit=cover&dpr=2.0)

Resized with DPR
Original
Original
Conversion en niveaux de gris
Grayscale
Effet de flou
Blurred
Original
Original
Flou appliqué (blur=5)
Blurred
Effet de rotation (rotation=15)
Rotated

Utilisation du Device Pixel Ratio (DPR)#

Ajustez la taille réelle de l'image pour le support d'écrans haute résolution. Calculez la taille réelle de l'image en multipliant la taille spécifiée par la valeur DPR.

Comment Fonctionne le DPR#

  • w=300&dpr=1.0 → Taille réelle de l'image : 300px (300 × 1.0)
  • w=300&dpr=1.5 → Taille réelle de l'image : 450px (300 × 1.5)
  • w=300&dpr=2.0 → Taille réelle de l'image : 600px (300 × 2.0)

Le navigateur affiche toujours à la taille spécifiée (300px), mais télécharge une image plus grande pour un rendu net.

DPR 1.0 (réel 300px)
DPR 1.0
DPR 1.5 (réel 450px)
DPR 1.5
DPR 2.0 (réel 600px)
DPR 2.0

Exemples d'Utilisation#

Résolution standard de bureau

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

Mobile Retina haute résolution

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

Ordre de Traitement des Transformations#

Les transformations d'images sont traitées dans l'ordre suivant :

  1. Resize (ajustement de taille) - DPR appliqué
  2. Rotation (rotation)
  3. Flip/Flop (retournement)
  4. Blur (effet de flou)
  5. Grayscale (conversion en niveaux de gris)
  6. Extract (extraction de région)
  7. Format (conversion de format)

Exemples de Transformations Complexes#

Vous pouvez combiner plusieurs transformations :

Ajustement de taille + niveaux de gris + flou

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

Extraction de région + rotation

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

Optimisation pour écrans haute résolution

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

Images responsives mobiles

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

Combinaison rotation et retournement

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

Performance et Cache#

CloudFront CDN#

Toutes les images transformées sont mises en cache sur CloudFront CDN pour une livraison rapide :

  • Première requête : Transformer l'image originale et la mettre en cache
  • Requêtes suivantes : Livraison instantanée depuis le cache
  • Durée du cache : 1 an

Optimisation Basée sur l'En-tête Accept#

Lorsque le paramètre format est auto, le format optimal est automatiquement sélectionné basé sur l'en-tête Accept du navigateur :

  • Navigateurs compatibles AVIF : Conversion au format AVIF
  • Navigateurs compatibles WebP : Conversion au format WebP
  • Navigateurs standards : Conversion au format JPEG/PNG

Limitations du Système et Protections#

Limitations de Traitement#

  • Taille maximale d'image : 4 096 x 4 096 pixels
  • Limite de pixels d'entrée : 268 402 689 pixels (environ 16K x 16K)
  • Intensité du flou : Maximum 20 (protection CPU)
  • Plage DPR : 1.0-4.0

Système de Fallback Automatique#

Gestion automatique lorsque des problèmes surviennent pendant la transformation :

  1. Erreurs de paramètres : Correction automatique des valeurs invalides
  2. Échecs de transformation : Retourne l'image originale
  3. Manque de mémoire : Les limitations de traitement assurent la sécurité du système
  4. Erreurs de format : Conversion au format JPEG par défaut

Optimisation Mémoire#

  • Cache désactivé : Cache mémoire Sharp non utilisé
  • Nettoyage automatique : Libération automatique des instances de bibliothèque Sharp après achèvement du traitement
  • Traitement unique : Concurrence limitée pour protection mémoire

Intégration et Utilisation#

Intégration Next.js (Bientôt Disponible)#

Actuellement en développement. Bientôt disponible.

Restez informé :

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,
  }}
/>;

Implémentation d'Images Responsives#

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`;
};
 
// Exemple d'utilisation
<picture>
  <source media="(min-width: 768px)" srcSet={getResponsiveUrl(baseUrl, 800)} />
  <img src={getResponsiveUrl(baseUrl, 400, true)} alt="Responsive" />
</picture>;

Étapes Suivantes#