API Vehicle Imagery v1.2.0

Des images de voitures de qualité studio pour chaque marque, modèle, année, variante, finition et vue, livrées sous forme d'URLs CDN signées avec format, taille, rapport d'aspect, couleur de peinture, ombre, transparence, ancrage et réflexion au sol à la demande.

URL de base

Tous les points de terminaison sont disponibles sous https://api.vehicleimagery.com.

Authentification

Chaque demande nécessite votre clé API dans l'en-tête x-api-key:

curl -H "x-api-key: YOUR_API_KEY" https://api.vehicleimagery.com/api/brands

Ce que votre clé peut faire (formats, ratios, fonctionnalités, marques) est retourné par /api/me. Les points de terminaison des docs (/api/openapi.json, /api/docs) sont publics et ne nécessitent pas de clé.

Comment cela fonctionne

1. Naviguez dans le catalogue jusqu'à une seule voiture: brand → model → year → variant → trim → view, par exemple GET /api/Abarth/124_Spider_Abarth/2016/Basis/base.
2. Résolvez une image en ajoutant la vue + options: GET /api/Abarth/124_Spider_Abarth/2016/Basis/base/front_left?format=webp&width=1200 → renvoie les métadonnées plus une image_url signée.
3. Intégrez image_url directement dans votre <img>. Elle est signée et verrouillée en transformation; les octets sont générés à la première demande et mis en cache sur le CDN pour la durée de vie de votre plan (par défaut 7 jours).

Add-on API v2: ensembles studio, rotations 360° et lifestyle *(nouveau)*

Les clés avec l'add-on API v2 bénéficient également de nos nouveaux ensembles d'images studio — dans le même catalogue et avec les mêmes appels. Vérifiez access dans /api/me: v1 = images standard, v2 = add-on, all = les deux. Sur l'endpoint trim, une voiture avec des images add-on liste groups à côté de views

• Vues standard (front, front_left … right) — mêmes URLs que d'habitude.
• Groupes studio : …/{trim}/{group} liste les images, …/{trim}/{group}/{image} résout une image:
• hero : prises de vue héroïques, vues en trois quarts, certaines au niveau du sol (8 images)
• steered : roues avant tournées, prises de trois hauteurs de caméra (8 images)
• extra : plus d'angles : tous les côtés et coins à hauteur des yeux, en hauteur et en bas, coins également à 30° et 45° (56 images)
• drone : vues en angle, vues en plongée et vues de dessus (7 images)
• Les noms des images indiquent où se trouve la caméra: le côté (front, front_left, left, rear_right …) plus _eye (au niveau des yeux), _high (au-dessus), _low (en bas), _ground (au niveau du sol), _30 / _45 (vue en coin à 30° / 45°), _steep (en oblique d'en haut) ou top (de haut en bas). Le nombre d'images par voiture peut varier; /api/getall et l'endpoint de groupe les montrent.
• Tours à 360° — …/{trim}/360 liste les anneaux (eye_level, low, high), …/{trim}/360/{ring} renvoie chaque image avec son propre image_url (une rotation nécessite toutes les images, dans l'ordre).
• Scènes de style de vie: …/{trim}/lifestyle liste les scènes, …/lifestyle/{scene} leurs images, …/lifestyle/{scene}/{image} résout une image.

Chaque point de terminaison de référence connaît l'add-on: /api/search et /api/getall incluent les voitures d'add-on (getall avec leurs groups), les /colors, /features et /all d'une voiture décrivent ses options d'add-on, et /api/options, /api/sizes, /api/views et /api/me ajoutent une section addon. Tout fonctionne également par identifiant stable (/api/id/{id}/…).

Les images supplémentaires prennent des options supplémentaires: lights, background (blanc, transparent ou n'importe quel hex), color en hex (ex. c8102e), windows=dark, plate (blank ou votre logo), fit, size et hotspots — voir *Résoudre une URL d'image signée*. Sans l'add-on, ces paramètres sont ignorés et aucun groupe n'est listé.

Noms et identifiants : toutes les voitures, standard et supplémentaires, utilisent la même nomenclature du catalogue (par exemple, Mercedes-Benz / C-Class, BMW / 5 series). Les noms utilisés avant le 5 octobre 2026 (par exemple, Mercedes / C-Klasse) résolvent toujours et répondent avec le nom actuel. Les noms ne contiennent jamais de barre oblique : là où le catalogue en écrit une, le nom a un tiret (par exemple, Chevrolet / C-K). Les voitures qui existent uniquement dans le supplément ont des identifiants à partir de 900000000; /api/id/{id}/… fonctionne pour elles comme pour toute autre voiture.

Vous avez un véhicule réel? *(Bêta)*

Si vous connaissez le numéro VIN ou l'immatriculation de la voiture au lieu de sa position dans le catalogue, les modules de recherche font les deux étapes en un seul appel: GET /vin/{vin} et GET /plate/{plate} décodent le véhicule et renvoient la correspondance la plus proche du catalogue avec des URL d'images signées à côté des données décodées. Les deux sont optionnels par clé — vérifiez features.vin et features.plate dans /api/me. Sans le module, ils renvoient 403.

Options d'image

Ajoutez à toute demande d'image: format, résolution, ratio, largeur, hauteur, qualité, couleur, ombre, transparence, sol, miroir. Toutes les options se combinent librement (par exemple, ?color=wine_red&shadow=true&format=webp&width=1200). L'ensemble complet filtré par plan se trouve dans /api/options.

Couleurs de peinture

Les voitures peuvent être repeintes sur demande. Les reflets, le chrome, le verre et l'intérieur restent inchangés. Seule la peinture change, fidèle à sa finition (unie ou métallisée). /api/colors liste l'ensemble du catalogue sous forme de paires { color_name, color_make }: les couleurs maison (black, white, blue, orange, wine_red — color_make: "Vehicleimagery") sont disponibles sur chaque voiture. Les couleurs de marque (par exemple, Kia *Racing Red*) appartiennent aux voitures de cette marque. L'endpoint /colors d'une voiture liste ce qui est affiché pour elle (couleurs maison + couleurs de sa marque). Toute couleur de catalogue active peut encore être demandée sur n'importe quelle voiture via ?color=. Détails: le guide *Paint colors* à /info/guides/colors.

Ombres, transparence et composition

Les ombres au sol du studio (shadow=true), les découpes transparentes (transparency=true) et la livraison opaque blanche sont produites au moment de la livraison pour chaque vue extérieure. La disponibilité est uniforme sur tout le catalogue.

Notes d'erreur (non fatales)

Lorsque une demande ne peut pas être satisfaite exactement, l'API ne échoue pas — elle revient à la valeur valide la plus proche et ajoute un court code au tableau errornotes (par exemple, Y01 = année la plus proche utilisée, S05 = ombre indisponible). La liste complète se trouve dans /api/errornotes.

Livraison et mise en cache des images

L'image_url renvoyée pointe vers le CDN, porte une signature ainsi qu'une date d'expiration, et est verrouillée à la transformation exacte — les clients ne peuvent pas la modifier. La première requête produit et met en cache les octets; chaque requête ultérieure est servie directement à partir du cache. Il suffit de déposer l'URL dans un <img src>.

De nouvelles images sont produites dans une file d'attente équitable : les plans avec une priorité plus élevée passent en premier, et les requêtes identiques qui arrivent en même temps ne sont produites qu'une seule fois. Le premier chargement d'une nouvelle combinaison prend généralement quelques secondes; l'en-tête de réponse X-Cache vous indique d'où elle provient (MISS = juste produite, HIT / HIT-R2 = cache, ORIGINAL = fichier source intact), X-Queue-Wait-Ms indique combien de temps elle a attendu. Si un très grand nombre de nouvelles images est produit en même temps, une URL d'image peut répondre 503 busy avec Retry-After: 5 — chargez-la simplement à nouveau quelques secondes plus tard.

Codes d'état

• 200 : succès. Vérifiez toujours errornotes pour les retombées silencieuses.
• 401 : clé API manquante ou invalide x-api-key.
• 403 : votre plan n'autorise pas la fonctionnalité, le format ou la marque demandée.
• 404 : aucune donnée pour ce chemin. Le message indique exactement ce qu'il faut vérifier.
• 503 — (URL des images uniquement) de nombreuses nouvelles images sont produites en ce moment; réessayez après les secondes dans Retry-After.

Conventions

• Les noms de marque, de modèle, de variante et de finition sont insensibles à la casse et acceptent les alias courants.
• Les années s'alignent sur la génération disponible la plus proche
• Les points de terminaison du catalogue renvoient JSON; les octets d'image proviennent uniquement de l'image_url signée.