Bild

Eine signierte Bild-URL auflösen

Holen/api/{brand}/{model}/{year}/{variant}/{trim}/{view}

Der Kern-Endpunkt. Gibt Metadaten plus eine signierte image_url zurück, die Sie direkt in ein <img> einbetten.

Jede Option als Abfrageparameter hinzufügen. Alles, was für das Auto nicht verfügbar ist oder nicht durch Ihren Plan erlaubt ist, fällt auf den nächstgelegenen gültigen Wert zurück und wird in errornotes gemeldet (anstatt zu scheitern).

Beispiele

?format=webp&width=1200 — WebP, 1200 Pixel breit.
?ratio=16:9&format=jpeg — auf 16:9 aufgefüllt.
?mirroring=true — Auto auf einem spiegelnden Showroom-Boden.
?transparency=true&format=png — Ausschnitt auf transparentem Hintergrund.
?color=wine_red — in der Hausfarbe wine_red lackiert.
?color=Racing%20Red&shadow=true — Kia Katalogfarbe plus Studio-Schatten.

API v2 add-on: for cars with add-on images the extra options below apply (lights, background, hex color, windows, plate, fit, size, hotspots), e.g. ?color=c8102e&windows=dark&size=1080p. With the add-on {view} can also be a studio group (hero, steered, extra, drone): that lists the group's images — see *API v2 Add-on*.

Pfadparameter

Name	Typ	Beschreibung
`brand` erforderlich	Zeichenkette	Markenname oder Alias (groß- und kleinschreibungsunabhängig).
`model` erforderlich	Zeichenkette	Modellname.
`year` erforderlich	Ganzzahl	Modelljahr (4-stellig). Wenn das genaue Jahr fehlt, wird die nächste verfügbare Generation verwendet (Fehlermeldung `Y01`).
`variant` erforderlich	Zeichenkette	Karosserie-Variante.
`trim` erforderlich	Zeichenkette	Ausstattungsvarianten.
`view` erforderlich	Zeichenkette	Ansicht Name - siehe /api/views (z.B. front, front_left, rear).

Abfrageparameter.

Name	Typ	Beschreibung
`format`	Zeichenkette	Lieferformat. `auto` wählt WebP. Original ist PNG. `pngwebpjpegavifauto`
`resolution`	Zeichenkette	Größen-/Qualitätsvorgabe (wird durch explizite Breite/Qualität überschrieben). `defaultthumbsmallmediumlargefull`
`ratio`	Zeichenkette	Auf ein Seitenverhältnis auffüllen. `default` = nativ. `1:14:33:216:916:102:121:95:43:44:52:39:16`
`width`	Ganzzahl	Explizite Breite in px (auf die Breitenleiter geschnappt).
`height`	Ganzzahl	Explizite Höhe in px.
`quality`	Ganzzahl	Encoder-Qualität (40–100).
`color`	Zeichenkette	Farbton nach Namen (Groß-/Kleinschreibung egal; Leerzeichen im URL-Format, z.B. `Racing%20Red`). Das Auto wird auf Anfrage umlackiert - Lackierung wahr, Reflexionen und Zierleisten erhalten. Die `/colors` eines Autos listet den angezeigten Satz (Hausfarben + die Farben seiner Marke). Jede aktive Farbe aus `/api/colors` kann angefordert werden. Unbekannte Farbe → Standardlack + Fehlermeldung `F04`. Kombinierbar mit jeder anderen Option. API v2 Zusatz: auch jede 6-stellige Hex-Farbe, z.B. `c8102e`.
`shadow`	Zeichenkette	Studio-Bodenschatten - erstellt zum Lieferzeitpunkt, verfügbar für jede Außenansicht. Mit `mirroring=true` steuert dies den Unterbodenschatten. `truefalse`
`transparency`	Zeichenkette	Transparenter Hintergrund mit Ausschnitt - verfügbar für jede Außenansicht (verwenden Sie mit PNG/WebP). `truefalse`
`ground`	Zeichenkette	Setzen Sie das Auto auf den Boden (benötigt eine transparente Variante). `true`
`mirroring`	Zeichenkette	Reflektierender Boden. `true` = mit Unterboden-Schatten, `clean` = nur Reflexion. Benötigt eine transparente Variante. `trueclean`
`lights`	Zeichenkette	API v2 add-on: Scheinwerfer an oder aus (Standard `off`). Nicht verfügbar für ein Bild → `off` + Fehlerhinweis `L26`. `onoff`
`background`	Zeichenkette	API v2 add-on: `white` (Standard), `transparent` oder eine 6-stellige Hex-Farbe wie `f4f4f4`. Nur Studiobilder (Lifestyle → Fehlerhinweis `B32`).
`windows`	Zeichenkette	API v2 add-on: `see_through` = Glas wie im Bild (Standard), `dark` = getönte Scheiben, durch die man nicht hindurchsehen kann. Nicht verfügbar → Fehlerhinweis `W28`. `see_throughdark`
`plate`	Zeichenkette	API v2 add-on: Kennzeichen — `none` = wie im Bild (Standard), `blank` = leeres Kennzeichen, `logo` = Ihr Logo auf dem Kennzeichen (in Ihrem Schlüssel eingerichtet; fehlt → leer + Fehlerhinweis `N30`). `noneblanklogo`
`fit`	Zeichenkette	API v2 add-on: wie das Auto ein `ratio` / `size` Feld füllt — `contain` füllt auf (Standard), `cover` schneidet ab. Lifestyle-Bilder decken immer ab. `containcover`
`size`	Zeichenkette	API v2 Add-on: längste Seite `2k` 2560 px, `1080p` 1920 px, `720p` 1280 px, `540p` 960 px, `360p` 640 px, `thumb` 320 px. `width` / `height` übersteigen `size`. `2k1080p720p540p360pthumb`
`hotspots`	Zeichenkette	API v2 add-on: `hotspots` zur Antwort hinzufügen — Interessante Punkte (Felgen, Scheinwerfer …) als Brüche 0–1 des Bildes, z.B. für interaktive Betrachter. `true`

Anfragen

curl "https://api.vehicleimagery.com/api/bmw/m4/2024/coupe/base/front?format=png&resolution=default" \
  -H "x-api-key: YOUR_API_KEY"

200 · Bildmetadaten einschließlich der signierten `image_url`.

[
  {
    "id": 47456,
    "brand": "Abarth",
    "model": "124_Spider_Abarth",
    "year": 2016,
    "variant": "Basis",
    "trim": "base",
    "view": "front_left",
    "resolution": "default",
    "ratio": "default",
    "format": "webp",
    "settings": {
      "color": "default",
      "shadow": false,
      "transparency": false,
      "watermark": false,
      "ground": false,
      "mirroring": false,
      "width": 800
    },
    "image_url": "https://cdn.vehicleimagery.com/source/01KVJC5S0S639G46CASP7EK8HG?f=webp&q=82&w=800&verify=…&expire=…"
  }
]

401 · Fehlender oder ungültiger `x-api-key`.

{
  "error": "Invalid API key"
}

403 · Planbeschränkung (Funktion, Format oder Marke nicht erlaubt) oder blockierter Anfrage.

{
  "error": "Mirroring is not allowed by your plan."
}

404 · Keine Daten für den angeforderten Pfad.

{
  "error": "Brand 'Xyz' not found — check /api/brands for valid brands."
}