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

Wie es funktioniert

1. 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.
2. 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.
3. 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.

Haben Sie ein reales Fahrzeug? *(Beta)*

Wenn Sie die VIN oder das Kennzeichen des Fahrzeugs anstelle seiner Katalogposition kennen, erledigen die Lookup-Erweiterungen beide Schritte in einem Aufruf: GET /vin/{vin} und GET /plate/{plate} dekodieren das Fahrzeug und geben die nächstgelegene Katalogübereinstimmung mit signierten Bild-URLs zusammen mit den dekodierten Daten zurück. Beide sind pro Schlüssel opt-in — prüfen Sie features.vin und features.plate in /api/me. Ohne die Erweiterung geben sie 403 zurück.

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.