# Format et qualité

Un JPEG stocké n'est pas tenu de repartir en JPEG. La même URL de téléchargement qui [redimensionne](/fr/docs/image-transforms) 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

```http
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 :

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

:::callout
**`ECO_IMAGE_FORMAT` ne régit pas cette route.** Cette variable d'environnement fixe la sortie par défaut de l'action d'automatisation `file.transformImage`. Les transformations d'URL négocient depuis `Accept` et honorent un `format` explicite — rien d'autre. Définir `ECO_IMAGE_FORMAT=jpeg` n'empêchera pas un navigateur annonçant l'AVIF de recevoir de l'AVIF ici.
:::

## Qualité

```http
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](/fr/docs/image-transforms) — dimensions, modes d'ajustement, stratégies de recadrage.
- [Presets et mise en cache](/fr/docs/image-presets-caching) — regrouper ces paramètres sous un nom.
- [Opérations sur les fichiers](/fr/docs/file-operations) — le point de terminaison ainsi décoré.
- [Écoconception](/fr/docs/ecoconception) — là où `ECO_IMAGE_FORMAT` s'applique réellement.
- [Variables d'environnement : services](/fr/docs/env-vars-services) — la référence `ECO_*`.