Skip to main content
View as Markdown

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 — 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 (S3, local, bytea) et s'appliquent au point de terminaison de téléchargement standard :

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.

# Explicit format
GET /api/buckets/{bucket}/files/photos/banner.png?format=webp

# Preserve source format, skip negotiation
GET /api/buckets/{bucket}/files/photos/banner.png?format=origin

# Automatic: negotiated from the Accept header
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.

Qualité

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é.

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. 
STORAGE_TRANSFORM_PRESETS='{"thumbnail":{"width":150,"height":150,"fit":"cover"},"preview":{"width":600,"quality":80},"avatar":{"width":64,"height":64,"fit":"cover","crop":"attention"}}'
# Apply a preset
GET /api/buckets/{bucket}/files/photos/profile.jpg?preset=avatar

# Preset with overrides — explicit params win
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