# Transformations d'image Sovrium transforme les images stockées à la volée via des paramètres de requête d'URL. La largeur, la hauteur, le format, la qualité et le recadrage sont appliqués au moment de la requête à l'aide de la bibliothèque [Sharp](https://sharp.pixelplumbing.com/) — aucun service d'image externe. Les sorties transformées sont mises en cache, et le fichier original n'est jamais modifié. Les transformations fonctionnent sur les fichiers de n'importe quel [backend de stockage](/fr/docs/buckets-overview#storage-backends) (S3, local, bytea) et s'appliquent au point de terminaison de téléchargement standard : ```http GET /api/buckets/{bucket}/files/photos/team-photo.jpg?width=400&height=300&fit=cover ``` ## Redimensionnement | Paramètre | Type | Plage | Par défaut | Description | | --------- | ------- | --------------- | ---------- | ------------------------------- | | `width` | integer | 1–2500 | original | Largeur cible en pixels. | | `height` | integer | 1–2500 | original | Hauteur cible en pixels. | | `fit` | string | voir ci-dessous | `contain` | Stratégie de redimensionnement. | Ne fournir qu'une seule dimension calcule automatiquement l'autre, en préservant le rapport d'aspect. Les valeurs hors de 1–2500 renvoient `400 Bad Request`. ### Modes de fit | Mode | Comportement | | --------- | ------------------------------------------------------------------------------------ | | `contain` | Tient dans les limites, en préservant le rapport d'aspect (peut ajouter des bandes). | | `cover` | Remplit les limites, en préservant le rapport d'aspect (peut recadrer les bords). | | `fill` | Étire aux dimensions exactes, en ignorant le rapport d'aspect. | | `inside` | Comme `contain`, mais n'agrandit jamais. | | `outside` | Comme `cover`, mais ne réduit jamais. | ## Conversion de format Convertissez vers des formats modernes pour réduire la taille des fichiers et améliorer les temps de chargement. ```http # Format explicite GET /api/buckets/{bucket}/files/photos/banner.png?format=webp # Préserver le format source, ignorer la négociation GET /api/buckets/{bucket}/files/photos/banner.png?format=origin # Automatique : négocié à partir de l'en-tête Accept GET /api/buckets/{bucket}/files/photos/banner.png Accept: image/avif,image/webp,image/* ``` | Format | Extension | Cas d'usage | | -------- | --------- | ------------------------------------------------------- | | `avif` | `.avif` | Meilleure compression, navigateurs les plus récents. | | `webp` | `.webp` | Forte compression, large prise en charge moderne. | | `jpeg` | `.jpg` | Compatibilité universelle. | | `png` | `.png` | Transparence, sans perte. | | `origin` | (source) | Préserve le format source, opte hors de la négociation. | Sans paramètre `format`, le serveur négocie le meilleur format pris en charge à partir de l'en-tête `Accept`. Le `Content-Type` de la réponse reflète toujours la sortie réelle. Une valeur `format` non prise en charge renvoie `400 Bad Request`. :::callout **AVIF est la valeur par défaut éco.** La posture frugale-par-défaut de Sovrium définit `ECO_IMAGE_FORMAT=avif` afin que le transcodage côté serveur favorise la charge utile la plus petite. Les opérateurs optent hors via [Écoconception](/fr/docs/ecoconception) ; `format=origin` opte hors par requête. ::: ## Qualité ```http GET /api/buckets/{bucket}/files/photos/hero.jpg?quality=95 GET /api/buckets/{bucket}/files/photos/hero.jpg?width=100&quality=30 ``` | Comportement | Résultat | | --------------------------------- | ----------------------------------------------------------------- | | `quality` accepte 1–100 | Les valeurs plus élevées produisent des fichiers plus volumineux. | | Par défaut | `80` lorsqu'omis. | | Hors plage | `400 Bad Request`. | | S'applique aux formats avec perte | JPEG, WebP, AVIF. | | Ignoré pour | La sortie PNG sans perte. | ## Recadrage Les stratégies de recadrage ne s'appliquent que lorsque `fit=cover` ; sinon le paramètre `crop` est ignoré. ```http GET /api/buckets/{bucket}/files/photos/team.jpg?width=300&height=300&fit=cover&crop=entropy GET /api/buckets/{bucket}/files/photos/team.jpg?width=300&height=300&fit=cover&crop=50,30 ``` | Stratégie | Syntaxe | Description | | --------- | -------------------------- | ---------------------------------------------------------------- | | center | `crop=center` (par défaut) | Recadre depuis le centre de l'image. | | entropy | `crop=entropy` | Recadrage intelligent par entropie de Shannon. | | attention | `crop=attention` | Recadrage intelligent par la stratégie d'attention de Sharp. | | focal | `crop=x,y` | Recadre autour d'un point focal (`x`,`y` en pourcentages 0–100). | Les valeurs de point focal hors de 0–100 renvoient `400 Bad Request`. ## Presets Définissez des presets de transformation nommés une fois via une variable d'environnement, puis demandez-les par leur nom. | Variable | Par défaut | Objectif | | --------------------------- | ---------- | ------------------------------ | | `STORAGE_TRANSFORM_PRESETS` | (aucun) | Chaîne JSON de presets nommés. | ```bash STORAGE_TRANSFORM_PRESETS='{"thumbnail":{"width":150,"height":150,"fit":"cover"},"preview":{"width":600,"quality":80},"avatar":{"width":64,"height":64,"fit":"cover","crop":"attention"}}' ``` ```http # Appliquer un preset GET /api/buckets/{bucket}/files/photos/profile.jpg?preset=avatar # Preset avec surcharges — les params explicites l'emportent GET /api/buckets/{bucket}/files/photos/profile.jpg?preset=thumbnail&quality=95 ``` | Comportement | Résultat | | --------------------------------------------- | -------------------------------------------------------- | | Preset connu | Applique sa largeur, hauteur, fit, qualité et recadrage. | | Params d'URL explicites aux côtés d'un preset | Surchargent les valeurs du preset. | | Nom de preset inconnu | `400 Bad Request`. | | `preset` utilisé quand aucun n'est configuré | `400 Bad Request`. | Les noms de preset doivent être alphanumériques avec des traits d'union (validés au démarrage). ## Mise en cache Les images transformées sont mises en cache afin que les requêtes répétées soient servies instantanément. | Mécanisme | Détail | | ------------------ | --------------------------------------------------------------------------------------------- | | En-tête de réponse | `Cache-Control: public, max-age=31536000, immutable` (1 an, adressé par contenu). | | `ETag` | Hachage du fichier source plus les paramètres de transformation. | | `If-None-Match` | Un ETag correspondant renvoie `304 Not Modified`. | | Cache disque | Stocké dans `STORAGE_TRANSFORM_CACHE_DIR`, indexé par `sha256(file_path + transform_params)`. | | Éviction | LRU, borné par `STORAGE_TRANSFORM_CACHE_MAX_SIZE`. | | Variable | Par défaut | Objectif | | ---------------------------------- | --------------- | --------------------------------------------- | | `STORAGE_TRANSFORM_CACHE_DIR` | Dossier temp OS | Répertoire pour les transformations en cache. | | `STORAGE_TRANSFORM_CACHE_MAX_SIZE` | `500` | Taille maximale du cache en Mo. | ## Préservation de l'original | Garantie | Comportement | | -------------------------------- | ------------------------------------------------------------------------------------------------------------- | | Les octets source sont immuables | Le fichier original est identique octet pour octet après n'importe quel nombre de requêtes de transformation. | | Requête sans param | Renvoie l'original non modifié. | | Suppression du cache | N'affecte jamais la disponibilité du fichier original. | | Fichiers non image (PDF, CSV) | Les params de transformation renvoient `400 Bad Request`. | | Types pris en charge | JPEG, PNG, WebP, AVIF, GIF, TIFF, SVG (SVG est transmis tel quel). | ## Pages associées - [Présentation des buckets](/fr/docs/buckets-overview) — backends et configuration des buckets. - [Opérations sur les fichiers](/fr/docs/file-operations) — téléversement, téléchargement, suppression. - [URL signées](/fr/docs/signed-urls) — les transformations peuvent être intégrées dans des URL signées. - [Champs de pièce jointe](/fr/docs/attachment-fields) — transformations de vignettes sur les pièces jointes d'enregistrement. - [Écoconception](/fr/docs/ecoconception) — `ECO_IMAGE_FORMAT` et la posture frugale-par-défaut. - [Variables d'environnement](/fr/docs/env-vars) — configuration des presets et du cache.