Loslegen

Vehicle Imagery API v1.2.0

Studioqualitäts-Fahrzeugbilder für jede Marke, jedes Modell, jedes Jahr, jede Variante, Ausstattung und Ansicht - geliefert als signierte CDN-URLs mit Format, Größe, Seitenverhältnis, Lackfarbe, Schatten, Transparenz, Bodenverankerung und Spiegelung des Bodens.

Basis-URL

Alle Endpunkte sind unter https://api.vehicleimagery.com live.

Authentifizierung

Jede Anfrage benötigt Ihren API-Schlüssel im x-api-key Header:

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

Was Ihr Schlüssel tun kann (Formate, Verhältnisse, Funktionen, Marken) wird von /api/me zurückgegeben. Die Docs-Endpunkte (/api/openapi.json, /api/docs) sind öffentlich und benötigen keinen Schlüssel.

Zwei Eingabearten

Das Auto kennen? Navigieren Sie im Katalog: brand → model → year → variant → trim → view. Ein reales Fahrzeug haben? Nutzen Sie die Lookup-Erweiterungen. GET /vin/{vin} oder GET /plate/{plate} wandeln eine VIN oder ein Kennzeichen direkt in Fahrzeugdaten um, plus Studiobilder des Autos, mit seiner echten Lackfarbe, sofern verfügbar. Erweiterungen werden pro Schlüssel aktiviert. /api/me zeigt, was Ihr Schlüssel kann.

Wie es funktioniert

Navigieren Sie durch den Katalog bis zu einem Auto: marke → modell → jahr → variante → ausstattung → ansicht, z.B. GET /api/Abarth/124_Spider_Abarth/2016/Basis/base.
Ein Bild auflösen durch Hinzufügen der Ansicht + Optionen: GET /api/Abarth/124_Spider_Abarth/2016/Basis/base/front_left?format=webp&width=1200 → gibt Metadaten plus eine signierte image_url zurück.
Embed image_url direkt in Ihr <img>. Es ist signiert und transformationsgesperrt. Die Bytes werden bei der ersten Anfrage generiert und auf dem CDN für die TTL Ihres Plans (Standard 7 Tage) zwischengespeichert.

Bildoptionen

Fügen Sie jeder Bildanfrage hinzu: format, resolution, ratio, width, height, quality, color, shadow, transparency, ground, mirroring. Alle Optionen kombinieren sich frei (z.B. ?color=wine_red&shadow=true&format=webp&width=1200). Der vollständige, plangefilterte Satz ist unter /api/options zu finden.

Lackfarben

Fahrzeuge können auf Anfrage umlackiert werden. Spiegelungen, Chrom, Glas und Innenraum bleiben unverändert. Nur die Lackierung ändert sich, entsprechend ihrer Ausführung (unifarben oder metallisch). /api/colors listet den gesamten Katalog als { color_name, color_make } Paare auf: die Hausfarben (black, white, blue, orange, wine_red — color_make: "Vehicleimagery") stehen für jedes Auto zur Verfügung. Markenfarben (z.B. Kia *Racing Red*) gehören zu den Fahrzeugen dieser Marke. Das eigene /colors Endpunkt eines Autos listet auf, was für es angezeigt wird (Hausfarben + die Farben seiner Marke). Jede aktive Katalogfarbe kann dennoch über ?color= für jedes Auto angefordert werden. Details: die Anleitung *Lackfarben* unter /info/guides/colors.

Schatten, Transparenz und Compositing

Studio-Bodenschatten (shadow=true), transparente Ausschnitte (transparency=true) und opake weiße Lieferung werden zum Lieferzeitpunkt für jede Außenansicht erstellt - die Verfügbarkeit ist im gesamten Katalog einheitlich.

Fehlerhinweise (nicht fatal)

Wenn eine Anfrage nicht genau erfüllt werden kann, schlägt die API nicht fehl. Sie greift auf den nächstgelegenen gültigen Wert zurück und fügt einen kurzen Code zum errornotes Array hinzu (z.B. Y01 = nächstes Jahr verwendet, S05 = Schatten nicht verfügbar). Die vollständige Liste finden Sie unter /api/errornotes.

Bildlieferung & Caching

Die zurückgegebene image_url zeigt auf das CDN, trägt eine Signatur plus ein Ablaufdatum und ist an die genaue Transformation gebunden - Kunden können sie nicht manipulieren. Die erste Anfrage rendert und zwischenspeichert die Bytes; jede spätere Anfrage wird direkt aus dem Cache geliefert. Setzen Sie einfach die URL in ein <img src> ein.

Statuscodes

200 — Erfolg. Überprüfen Sie immer errornotes auf stille Rückfälle.
401 — fehlt oder ungültig x-api-key.
403 — Ihr Plan erlaubt das angeforderte Feature, Format oder die Marke nicht.
404 — keine Daten für diesen Pfad. Die Nachricht benennt genau, was zu überprüfen ist.

Konventionen

Marken-/Modell-/Varianten-/Ausstattungsnamen sind groß- und kleinschreibungsunabhängig und akzeptieren gängige Aliase.
Jahre schnappen sich die nächste verfügbare Generation.
Katalog-Endpunkte geben JSON zurück. Bildbytes kommen nur von der signierten image_url.