API Vehicle Imagery v1.1.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).

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