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 de l'AVIF 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
avif	image/avif	Charge utile la plus légère. Support large mais pas universel.
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.

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/avif,image/webp,image/*

Accept contient	Sortie
image/avif	AVIF
image/webp	WebP
Ni l'un ni l'autre	Les octets originaux, intacts

AVIF l'emporte sur WebP quand les deux sont proposés. 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é.

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, WebP, AVIF.
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 format du tout. Laissez la négociation opérer : vous obtenez l'AVIF 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 recadrage — dimensions, modes d'ajustement, stratégies de recadrage.
• 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 — là où ECO_IMAGE_FORMAT s'applique réellement.
• Variables d'environnement : services — la référence ECO_*.