Comment afficher une image studio de voiture sur chaque annonce d’une place de marché

Un site de petites annonces ou un catalogue d’achat automobile vit ou meurt par sa grille. Chaque carte a besoin d’une image dès que l’annonce existe, et la photo du vendeur arrive plus tard, voire jamais, sous un angle quelconque et dans une allée quelconque. La photo d’illustration a le problème inverse : une photo de presse sous licence existe pour les voitures populaires des années populaires, sous l’angle et sur le fond choisis par le constructeur, et pour rien d’autre. Un catalogue qui couvre de 1990 au millésime actuel présente des dizaines de milliers de manques.

Ce que veulent les équipes qui créent ces sites est ennuyeux, au meilleur sens du terme : une image studio par millésime, le même angle et la même teinte pour toutes, transparente pour s'intégrer à n'importe quel fond de carte, et assez légère pour être servie dix mille fois par jour.

Les catalogues construits aujourd'hui sur l'API ont tous la même structure, qu'il s'agisse d'un site de petites annonces qui alimente ses annonces, d'une application d'achat automobile qui affiche ses fiches comparatives ou d'une application mobile qui montre une image principale par véhicule :

• Un remplissage initial, puis un flux régulier. Des milliers de rendus en quelques heures pour couvrir le catalogue, puis une poignée par jour au fil des nouveaux millésimes et des demandes.
• Un angle, une peinture, ou une courte palette. La plupart choisissent front-3-4 ou side en argent ou en blanc. Un catalogue d’achat qui laisse l’utilisateur choisir une couleur génère quelques teintes prédéfinies par véhicule ; chacune représente une image de véhicule de plus, pas un nouveau pipeline.
• Du WebP dans un cadre fixe. De 512 à 1024 pixels de large, livré exactement dans le cadre qu’utilise la carte : le front-end n’a jamais à recadrer l’image ni à ajouter de bandes.
• Stockés par identifiant de véhicule. Les rendus sont déposés sur le stockage objet ou le CDN de l'équipe, ou les pages chargent des URL signées ; dans les deux cas, la clé est l'identifiant veh_… stable du catalogue, et non une chaîne marque-modèle-année.

La suite de cette page présente ce pipeline, étape par étape, avec le code. Elle suppose une clé API dotée du scope images:read et un forfait dimensionné pour le catalogue (voir la FAQ).

L'échec le plus courant dans la construction d'un catalogue ne vient pas du rendu, mais de l'orthographe. Un build qui génère les chaînes de marque et de modèle à partir d'une autre base de données peut consacrer la plupart de ses requêtes à des 404 vehicle_not_found : gratuites, mais chacune représente un aller-retour inutile, et la grille se retrouve trouée. La solution : laisser le catalogue vous dire ce qui existe. GET /api/v1/vehicles est gratuit, ne nécessite aucune clé, et chaque modèle renvoyé porte un identifiant de véhicule stable (veh_ suivi de 13 caractères) qui ne change jamais d'un déploiement ou d'une version du catalogue à l'autre. Stockez cet identifiant sur l'annonce et utilisez-le pour le rendu.

?make=porsche&model=911 liste toutes les années d'un modèle avec un id par année, et ?q= effectue une recherche en texte libre lorsqu'un vendeur saisit un nom. Le même catalogue est publié sous forme de package ouvert @meterapp/vehicle-db, ce qui permet aux listes déroulantes et à la validation de fonctionner hors ligne sur une liste identique. Dans les deux cas, à la fin de cette étape, vous disposez d'une liste d'id, et plus rien en aval n'a jamais à épeler le nom d'une voiture.

Les annonces qui nomment déjà leurs voitures selon l'orthographe d'une autre base de données sont mises en correspondance en un seul appel : POST /api/v1/vehicles/check en lit jusqu'à 2 000 comme le ferait un rendu et répond pour chacune avec son identifiant de véhicule, les véhicules réels les plus proches lorsque le catalogue ne contient pas cette voiture, ou un échec à ignorer dans toutes les vues et couleurs. car-image check listings.csv --out checked.csv réécrit les identifiants dans le fichier. C'est gratuit, et cela vous évite de découvrir les lacunes une 404 après l'autre.

Définissez la vignette une fois pour toutes et encodez-la dans la chaîne de requête. Tout ce qui suit vehicle= ci-dessous est un choix de cadrage que vous faites une seule fois pour tout le catalogue :

• w=800&h=600&fit=contain produit exactement du 800×600 avec la voiture entièrement visible et une marge transparente autour, pour que chaque carte ait le même canevas. fit=cover remplit plutôt le cadre et recadre au centre.
• trim=1&padding=8 recadre sur le contour de la voiture avant l'ajustement, avec une marge de 8 % de son plus grand côté, si bien qu'un Suburban et une Miata remplissent le cadre de la même façon au lieu de flotter dans l'image source.
• color=silver est la valeur par défaut et la teinte neutre la plus sûre ; chacun des 15 préréglages ou n'importe quel code hexadécimal compte de la même façon, pour une image de véhicule.
• format=webp est l'encodage avec canal alpha sans perte le plus compact. Lorsqu'un navigateur charge directement l'URL (URL signées, étape 4), format=auto négocie WebP ou PNG selon le client.

La réponse contient ETag, X-Image-Source (cache ou generated) et X-Vehicle-Id, le véhicule du catalogue qui a été servi. Conservez l’ETag avec le fichier : une requête ultérieure avec If-None-Match renvoie 304 et ne coûte rien, ce qui permet à une resynchronisation nocturne de rester gratuite.

Trois limites encadrent un remplissage initial, et chacune se signale dans les en-têtes plutôt que d’échouer en silence :

• Requêtes par minute. 120 par clé avec Free et Pro, 600 avec Business, 1 200 avec Enterprise, plus une limite par compte couvrant toutes les clés. Chaque réponse authentifiée comporte RateLimit-Remaining ; une réponse 429 comporte Retry-After. Quatre à huit requêtes simultanées suffisent largement.
• Nouvelles vues de véhicule. La première requête pour une vue de véhicule que nous n’avons pas encore préparée est un peu plus longue, le temps que nous la préparions pour qu’elle puisse être affichée dans n’importe quelle couleur ; toutes les requêtes suivantes, dans n’importe quelle couleur, sont servies depuis le cache. La préparation de nouvelles vues puise dans la part du budget de rendu quotidien attribuée au compte (2 % en Free, 10 % en Pro, 25 % en Business, 50 % en Enterprise). Au-delà, un nouveau rendu répond 429 avec code: account_generation_cap et reset_at (minuit UTC), rien n’est facturé et les images en cache continuent d’être servies. Un import massif de rattrapage se fait en quelques soirées, pas en une seule.
• Images de véhicule par mois. Free en inclut 100, Pro 2 500, Business 10 000 ; Enterprise se négocie. Au-delà de ce quota, une requête pour une image pas encore comptée ce mois-ci renvoie 402 (plan_image_limit) et n’est pas décomptée ; une image déjà comptée ce mois-ci est toujours servie, si bien qu’une grille en production ne casse jamais.

Les échecs de rendu (502) restituent automatiquement leur image de véhicule, les requêtes simultanées pour une même nouvelle variante partagent un seul rendu, et un simple GET peut être relancé sans risque. Le SDK relance automatiquement les erreurs 429 et 503 en respectant Retry-After, et ne relance jamais une erreur 402.

Il existe deux bonnes façons de présenter l'image à un acheteur, et les intégrations de catalogue utilisent les deux :

• Stockez les fichiers. Enregistrez chaque rendu dans votre propre stockage d’objets ou CDN sous son identifiant de véhicule et servez-le comme n’importe quelle autre ressource. C’est la bonne solution pour une grille affichée des millions de fois : aucun appel vers nos serveurs à chaque chargement, et la licence d’un forfait payant couvre les copies que vous conservez pour servir votre produit.
• Générez des URL signées. POST /api/v1/image-urls accepte jusqu’à cinquante images par appel, compte l’image de chaque URL comme une image de véhicule du mois au moment de sa génération, et renvoie des URL sans clé que le navigateur charge directement. Définissez ttl_seconds jusqu’à sept jours ; ajoutez renew: true pour les pages d’annonces qui restent en ligne plus longtemps (un renouvellement compte l’image une fois dans le mois où il a lieu, et rien de plus si elle a déjà été comptée ce mois-là). Limitez la clé aux origines de votre site dans le tableau de bord, et une URL copiée ailleurs répondra 403.

Envoyez un Idempotency-Key par page d’annonces lorsque vous générez des URL par lots : un appel relancé avec la même clé et le même corps rejoue la première réponse et ne décompte rien de plus.

Cherchez d’abord : GET /api/v1/vehicles?q= trouve un modèle par nom, par préfixe ou par correspondance approximative, et POST /api/v1/images/resolve transforme une expression en texte libre en paramètres exacts, avec un indice de confiance exploitable. Ce qui manque encore ensuite a sa place sur le tableau des demandes : POST /api/v1/requests crée la demande ou, si une demande ouverte existe déjà pour la même marque, le même modèle et la même année, lui ajoute un vote au lieu de créer un doublon. Le catalogue lui-même est open source, et les ajouts profitent à tous les clients.

Tout le pipeline s’exécute depuis la CLI, sans la moindre ligne de code ; c’est ainsi que plusieurs catalogues de l’API ont été alimentés :

• SDK : client.vehicles({ year, makeId }) pour énumérer, client.getImage({ vehicle, … }) pour générer le rendu, client.createImageUrls(…) pour des lots d'URL signées. Consultez la documentation des images pour tous les paramètres.
• MCP : un assistant connecté à https://carimage.dev/api/mcp dispose du même catalogue (search_vehicles, resolve_vehicle) et des mêmes rendus (get_car_image, create_car_image_urls) : c’est le bon outil pour un responsable de catalogue qui ajoute un véhicule à la main, et le mauvais pour un import rétroactif de milliers de véhicules. Utilisez pour cela la CLI ou le SDK, et gardez l’assistant pour les cas restants. La configuration est décrite sur la page MCP.