Format et qualité
Un JPEG stocké n'est pas tenu de repartir en JPEG. La même URL de téléchargement qui redimensionne sait aussi transcoder, et par défaut elle le fait d'elle-même — un navigateur moderne reçoit du WebP depuis un PNG original sans que personne ne l'ait demandé.
Format explicite
GET /api/buckets/photos/files/{key}?format=webp| Valeur | Sortie | À utiliser pour |
|---|---|---|
webp |
image/webp |
Bonne compression, universelle en pratique aujourd'hui. |
jpeg |
image/jpeg |
Photos, quand rien ne peut être supposé du client. |
png |
image/png |
Transparence et sortie sans perte. |
origin |
source | Renoncer au transcodage pour cette requête. |
Le Content-Type de la réponse reflète toujours ce qui a réellement été produit. Une valeur non reconnue — bmp, tiff — répond 400.
L'AVIF n'est pas disponible. Le pipeline d'images de Sovrium s'appuie sur les encodeurs du runtime Bun, et ceux-ci n'embarquent pas d'encodeur AV1 sous Linux — la plateforme sur laquelle tournent le binaire et l'image Docker. Une option AVIF aurait donc fonctionné sur certaines machines et échoué sur d'autres : format=avif répond 400, comme toute autre valeur non prise en charge. Le format moderne proposé est le WebP : il compresse presque aussi bien, conserve la transparence, et tous les navigateurs sortis depuis 2020 le lisent.
Négociation automatique
Omettez format et le serveur lit l'en-tête Accept de la requête :
GET /api/buckets/photos/files/{key}
Accept: image/webp,image/*Accept contient |
Sortie |
|---|---|
image/webp |
WebP |
| Sinon | Les octets originaux, intacts |
C'est pourquoi un simple <img src> sans chaîne de requête obtient malgré tout un format moderne dans un navigateur moderne, et l'original intact dans un navigateur ancien — sans élément <picture>, sans jonglage de srcset, sans détection d'agent utilisateur côté serveur.
format=origin est la façon de court-circuiter la négociation délibérément : utilisez-le quand un consommateur en aval a besoin des octets stockés exacts, ou quand vous cherchez à savoir ce qui a réellement été téléversé.
Deux pipelines, deux règles. L'action d'automatisation file.transformImage encode en WebP lorsqu'elle convertit sans nommer d'outputFormat ; un simple redimensionnement y conserve le format source. Cette route ignore ces deux règles : elle négocie depuis Accept et honore un format explicite, rien d'autre. Aucune variable d'environnement ne modifie l'une ou l'autre.
Qualité
GET /api/buckets/photos/files/{key}?quality=95
GET /api/buckets/photos/files/{key}?width=100&quality=30| Comportement | Détail |
|---|---|
| Plage acceptée | Entier, de 1 à 100 inclus. |
| Défaut | 80 si omis. |
| S'applique à | Les sorties avec perte — JPEG et WebP. |
| Ignoré pour | PNG, qui est sans perte. |
| Hors plage, ou non entier | 400 |
Quatre-vingts n'est pas une valeur de remplissage : c'est à peu près le point où la qualité supplémentaire cesse d'être visible et ne devient plus que des octets. Passer à 95 peut doubler la charge utile pour une différence que la plupart des spectateurs ne verront pas sur la plupart des images.
L'association à retenir est width avec une quality basse. Une vignette de 100 pixels de large en quality=30 pèse une fraction d'une vignette pleine qualité et paraît identique à cette taille, car les artefacts de compression sont eux-mêmes réduits par le redimensionnement. Réservez la haute qualité aux images destinées à être vues en grand.
Choisir en pratique
Trois réglages par défaut qui couvrent presque tous les cas :
- Images de contenu dans une page — pas de
formatdu tout. Laissez la négociation opérer : vous obtenez le WebP là où il aide, et la justesse partout ailleurs. - Vignettes et avatars —
?width=…&quality=60. La taille fait le travail ; abaisser la qualité est presque gratuit. - Téléchargements demandés par un utilisateur —
?format=origin. Quelqu'un qui clique sur « télécharger l'original » le pense.
Pages associées
- Redimensionnement et ajustement — dimensions et les deux modes d'ajustement.
- Presets et mise en cache — regrouper ces paramètres sous un nom.
- Opérations sur les fichiers — le point de terminaison ainsi décoré.
- Écoconception — la posture environnementale de la plateforme et ses leviers.
- Variables d'environnement : services — la référence
ECO_*.
Dernière mise à jour 1 septembre 2026
Cette documentation a été rédigée avec de l'IA : des erreurs ou du contenu obsolète sont donc possibles. Sovrium est en bêta. Les contributions et corrections sont les bienvenues.