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

Deux façons d'entrer

Connaissez-vous la voiture? Naviguez dans le catalogue: brand → model → year → variant → trim → view. Avez-vous un véhicule réel? Utilisez les modules de recherche — GET /vin/{vin} ou GET /plate/{plate} transforment un numéro VIN ou une plaque d'immatriculation en données de véhicule *plus* des images de studio de cette voiture, avec sa couleur de peinture réelle appliquée si disponible. Les modules sont activés par clé; /api/me montre ce que la vôtre peut faire.

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).

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 retourné pointe vers le CDN, porte une signature ainsi qu'une date d'expiration, et est verrouillé à la transformation exacte - les clients ne peuvent pas la modifier. La première demande rend et met en cache les octets; chaque demande ultérieure est servie directement à partir du cache. Il suffit de déposer l'URL dans un <img src>

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.

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.