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 Name (Groß-/Kleinschreibung egal; Leerzeichen im URL-Format codieren, z.B. `Racing%20Red`). Das Auto wird auf Anfrage umlackiert - Finish-true, Reflexionen und Zierleisten erhalten. Die `/colors` eines Autos listet seinen gezeigten Satz (Hausfarben + die Farben seiner Marke) auf; jede aktive Farbe aus `/api/colors` kann angefordert werden. Unbekannte Farbe → Standardlack + Fehlermeldung `F04`. Kombinierbar mit jeder anderen Option. API v2 Add-on: Katalogfarben kommen mit ihrem echten Finish (metallisch, Perl, matt, seidenmatt, Chrom, Aluminium, Carbon). Auch jede 6-stellige Hex-Farbe, z.B. `c8102e` (gloss), oder eine Hex-Farbe mit einem Finish: `<finish>_<hex>`, z.B. `metallic_315fbf`, `matte_283b56`, `carbon_545454`, `chrome_eac972`; metallisch, Perl und seidenmatt nehmen eine optionale zweite Farbe für den Effekt, z.B. `metallic_315fbf_5693f9`. Finishes: `solid`, `metallic`, `pearl`, `satin`, `matte` (auch `matt`), `chrome`, `aluminium`, `carbon`.
`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 Zusatz: Scheinwerfer ein- oder ausgeschaltet. Standardmäßig `on`: ohne den Parameter kommt das Bild mit eingeschalteten Lichtern, wo immer das Bild sie hat; senden Sie `lights=off` für ein Bild ohne Lichter. Ein Bild ohne Lichtvariante kommt einfach ohne Lichter; mit `lights=on` enthält es auch den 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 + Fehlernotiz `N30`), `text` = Ihr eigener Text aus `plate_text` (muss für Ihren Schlüssel aktiviert sein, siehe `addon.plate_text` in `/api/me`; andernfalls Fehlernotiz `O31`). `noneblanklogotext`
`plate_text`	Zeichenkette	API v2 add-on: der Text für `plate=text` — bis zu 10 Zeichen: Buchstaben, Ziffern, Leerzeichen und `-` `.` `&`. Auf dem Kennzeichen wie gesendet geschrieben (Groß- und Kleinschreibung bleibt erhalten), zentriert und so groß wie das Kennzeichen es zulässt. Fehlt, zu lang oder andere Zeichen → `400`.
`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`
`version`	Zeichenkette	Ergebnisse nur von einer Version: `v1` = Standardbilder, `v2` = API v2 Zusatz (kein Rückfall auf Standardbilder). Ohne diesen Parameter: alles, was Ihr Schlüssel erlaubt. Nicht erlaubt für Ihren Schlüssel → `403`. `v1v2`

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