API Médias
Importez des fichiers, classez-les en dossiers, voyez où une image est utilisée et définissez le point focal des vignettes.
2 min de lecture
Sur cette page
Vue d'ensemble
Les endpoints médias sont sous /api/v1/media et utilisent les permissions products:* (products:read pour lister, products:create pour importer, products:update pour modifier, products:delete pour supprimer). Le rattachement aux produits passe par les endpoints médias produit ; cette page couvre la médiathèque elle-même.
Endpoints
| Méthode | Chemin | Rôle |
|---|---|---|
GET | /media | Liste des fichiers. page, limit, filter[folderId] (un identifiant de dossier, ou none pour les fichiers non classés), filter[mimeType], search. |
POST | /media/upload | Multipart file (image ou PDF, 50 Mo max) + altText, folderId optionnels. Les images reçoivent des variantes vignette / medium / large en arrière-plan. |
GET | /media/{id} | Un fichier avec url, thumbnailUrl, width, height, folderId, focalX, focalY. |
PATCH | /media/{id} | { folderId?, altTextI18n?, tags?, focalX?, focalY? }. folderId: null déclasse le fichier. |
GET | /media/{id}/usage | Depuis v2.13. Produits utilisant le fichier : { data: [{ id, sku, nameI18n, status, isPrimary, channels: [{ id, name, platform }] }] }. |
DELETE | /media/{id} | Supprime le fichier et ses variantes. |
GET | /media/folders | Liste plate des dossiers avec parentId et mediaCount ; l'arborescence se construit côté client. |
POST | /media/folders | { name, parentId? }. |
PATCH | /media/folders/{id} | Depuis v2.13. { name?, parentId? } — renommer ou déplacer. 400 si le déplacement crée un cycle. |
DELETE | /media/folders/{id} | Depuis v2.13. Les fichiers qu'il contient deviennent non classés (jamais supprimés). 409 tant que le dossier a des sous-dossiers. |
Point focal
Depuis v2.13. focalX / focalY sont des fractions de la largeur et de la hauteur (0–1, trois décimales). Envoyez les deux ou aucun ; null les efface. Une fois définis, la vignette est recadrée en carré autour de ce point ; les variantes medium et large ainsi que l'original ne sont jamais modifiés, donc url reste stable et les canaux continuent de pousser la même image.
PATCH /api/v1/media/8a2f…/
{ "focalX": 0.62, "focalY": 0.35 }Les variantes sont régénérées de façon asynchrone — thumbnailUrl change en quelques secondes.