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.

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.

API v2 Add-on: Studio-Sets, 360°-Rundgänge und Lifestyle *(neu)*

Schlüssel mit dem API v2 Add-on erhalten auch unsere neuen Studio-Bildsätze — im gleichen Katalog und mit denselben Aufrufen. Prüfen Sie access in /api/me: v1 = Standardbilder, v2 = Add-on, all = beides. Am Trim-Endpunkt listet ein Auto mit Add-on-Bildern groups neben views:

• Standardansichten (front, front_left … right) — dieselben URLs wie immer.
• Studio-Gruppen list …/{trim}/{group} the images, …/{trim}/{group}/{image} resolves one:
• hero — Hauptaufnahmen, Dreiviertelansichten, einige vom Boden aus (8 Bilder)
• steered — Vorderräder eingeschlagen, aus drei Kamerahöhen (8 Bilder)
• extra — mehr Winkel: jede Seite und Ecke auf Augenhöhe, hoch und tief, Ecken auch bei 30° und 45° (56 Bilder)
• drone — aus der Vogelperspektive: schräge Aufnahmen, steile Ansichten und direkt von oben (7 Bilder)
• Bildnamen geben an, wo sich die Kamera befindet: die Seite (front, front_left, left, rear_right …) plus _eye (Augenhöhe), _high (von oben), _low (tief), _ground (auf Bodenhöhe), _30 / _45 (Eckansicht bei 30° / 45°), _steep (schräg von oben) oder top (von oben). Die Anzahl der Bilder pro Auto kann variieren; /api/getall und der Gruppen-Endpunkt zeigen sie.
• 360° Drehungen — …/{trim}/360 listet die Ringe auf (eye_level, low, high), …/{trim}/360/{ring} gibt jeden Frame mit seiner eigenen image_url zurück (eine Drehung benötigt alle davon, in der richtigen Reihenfolge).
• Lifestyle-Szenen: …/{trim}/lifestyle listet die Szenen auf, …/lifestyle/{scene} deren Bilder, …/lifestyle/{scene}/{image} löst eines auf.

Jede Referenz-Endpunkt kennt das Add-on: /api/search und /api/getall enthalten Add-on-Fahrzeuge (getall mit ihren groups), ein Fahrzeugs /colors, /features und /all beschreiben seine Add-on-Optionen, und /api/options, /api/sizes, /api/views und /api/me fügen einen addon Abschnitt hinzu. Alles funktioniert auch über eine stabile ID (/api/id/{id}/…).

Zusatzbilder bieten zusätzliche Optionen: lights, background (weiß, transparent oder jeder Hex-Wert), color als Hex-Wert (z.B. c8102e), windows=dark, plate (blank oder Ihr logo), fit, size und hotspots — siehe *Resolve a signed image URL*. Ohne das Add-on werden diese Parameter ignoriert und keine Gruppen aufgelistet.

Namen & IDs: alle Autos, Standard und Zusatz, verwenden die gleiche Katalogbezeichnung (z. B. Mercedes-Benz / C-Class, BMW / 5 series). Namen, die vor dem 5. Oktober 2026 verwendet wurden (z. B. Mercedes / C-Klasse), lösen sich weiterhin auf und geben den aktuellen Namen zurück. Namen enthalten nie einen Schrägstrich: wo der Katalog einen schreibt, hat der Name einen Bindestrich (z. B. Chevrolet / C-K). Autos, die nur im Zusatz existieren, haben IDs ab 900000000; /api/id/{id}/… funktioniert für sie wie für jedes andere Auto.

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, enthält eine Signatur plus ein Ablaufdatum und ist an die genaue Transformation gebunden - Kunden können sie nicht manipulieren. Die erste Anfrage erstellt und zwischenspeichert die Bytes. Jede spätere Anfrage wird direkt aus dem Cache geliefert. Einfach die URL in ein <img src> einfügen.

Neue Bilder werden in einer fairen Warteschlange erstellt: Pläne mit höherer Priorität gehen zuerst, und identische Anfragen, die zur gleichen Zeit eintreffen, werden einmal erstellt. Die erste Ladung einer neuen Kombination dauert in der Regel einige Sekunden. Der Antwortheader X-Cache zeigt Ihnen, woher es stammt (MISS = gerade erstellt, HIT / HIT-R2 = Cache, ORIGINAL = unveränderte Quelldatei), X-Queue-Wait-Ms zeigt, wie lange es gewartet hat. Wenn eine sehr große Anzahl neuer Bilder gleichzeitig erstellt wird, kann eine Bild-URL mit 503 busy und Retry-After: 5 antworten. Laden Sie es einfach ein paar Sekunden später erneut.

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.
• 503 — (nur Bild-URLs) es werden gerade viele neue Bilder erstellt; wiederholen Sie den Versuch nach den Sekunden in Retry-After.

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.