Image

Resolve a signed image URL

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

The core endpoint. Returns metadata plus a signed image_url you embed directly in an <img>.

Add any option as a query param. Anything not available for the car or not allowed by your plan falls back to the closest valid value and is reported in errornotes (rather than failing).

Examples

?format=webp&width=1200 — WebP, 1200 px wide.
?ratio=16:9&format=jpeg — padded to 16:9.
?mirroring=true — car on a reflective showroom floor.
?transparency=true&format=png — cut-out on transparent background.
?color=wine_red — repainted in the wine_red house color.
?color=Racing%20Red&shadow=true — Kia catalog paint plus studio shadow.

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*.

Path parameters

Name	Type	Description
`brand` required	string	Brand name or alias (case-insensitive).
`model` required	string	Model name.
`year` required	integer	Model year (4-digit). If the exact year is missing, the nearest available generation is used (errornote `Y01`).
`variant` required	string	Body variant.
`trim` required	string	Trim level.
`view` required	string	View name — see /api/views (e.g. front, front_left, rear).

Query parameters

Name	Type	Description
`format`	string	Delivery format. `auto` picks WebP. Original is PNG. `pngwebpjpegavifauto`
`resolution`	string	Size/quality preset (overridden by explicit width/quality). `defaultthumbsmallmediumlargefull`
`ratio`	string	Pad to an aspect ratio. `default` = native. `1:14:33:216:916:102:121:95:43:44:52:39:16`
`width`	integer	Explicit width in px (snapped to the width ladder).
`height`	integer	Explicit height in px.
`quality`	integer	Encoder quality (40–100).
`color`	string	Paint color by name (case-insensitive; URL-encode spaces, e.g. `Racing%20Red`). The car is repainted on demand — finish-true, reflections and trim preserved. A car's `/colors` lists its shown set (house colors + its brand's colors); ANY active color from `/api/colors` can be requested. Unknown color → default paint + errornote `F04`. Combines with every other option. API v2 add-on: catalogue colours come with their real finish (metallic, pearl, matte, satin, chrome, aluminium, carbon). Also any 6-digit hex paint colour, e.g. `c8102e` (gloss), or a hex colour with a finish: `<finish>_<hex>`, e.g. `metallic_315fbf`, `matte_283b56`, `carbon_545454`, `chrome_eac972`; metallic, pearl and satin take an optional second colour for the effect, e.g. `metallic_315fbf_5693f9`. Finishes: `solid`, `metallic`, `pearl`, `satin`, `matte` (also `matt`), `chrome`, `aluminium`, `carbon`.
`shadow`	string	Studio ground shadow — produced at delivery time, available for every exterior view. With `mirroring=true` this controls the underbody shadow instead. `truefalse`
`transparency`	string	Transparent cut-out background — available for every exterior view (use with PNG/WebP). `truefalse`
`ground`	string	Sit the car on the ground (needs a transparent variant). `true`
`mirroring`	string	Reflective floor. `true` = with underbody shadow, `clean` = reflection only. Needs a transparent variant. `trueclean`
`lights`	string	API v2 add-on: headlights on or off. Default `on`: without the parameter the image comes with the lights on wherever the image has them; send `lights=off` for an image without lights. An image with no light variant simply comes without lights; with `lights=on` it also carries errornote `L26`. `onoff`
`background`	string	API v2 add-on: `white` (default), `transparent`, or a 6-digit hex colour like `f4f4f4`. Studio images only (lifestyle → errornote `B32`).
`windows`	string	API v2 add-on: `see_through` = glass as in the image (default), `dark` = privacy glass you cannot see through. Not available → errornote `W28`. `see_throughdark`
`plate`	string	API v2 add-on: licence plate — `none` = as in the image (default), `blank` = empty plate, `logo` = your logo on the plate (set up on your key; missing → blank + errornote `N30`), `text` = your own text from `plate_text` (must be enabled for your key, see `addon.plate_text` in `/api/me`; otherwise errornote `O31`). `noneblanklogotext`
`plate_text`	string	API v2 add-on: the text for `plate=text` — up to 10 characters: letters, digits, spaces and `-` `.` `&`. Written on the plate as sent (upper and lower case kept), centred and as large as the plate allows. Missing, too long or other characters → `400`.
`fit`	string	API v2 add-on: how the car fills a `ratio` / `size` box — `contain` pads (default), `cover` crops. Lifestyle images always cover. `containcover`
`size`	string	API v2 add-on: longest side — `2k` 2560 px, `1080p` 1920 px, `720p` 1280 px, `540p` 960 px, `360p` 640 px, `thumb` 320 px. `width` / `height` win over `size`. `2k1080p720p540p360pthumb`
`hotspots`	string	API v2 add-on: add `hotspots` to the response — points of interest (rims, headlights …) as fractions 0–1 of the image, e.g. for interactive viewers. `true`
`version`	string	Results from one version only: `v1` = standard images, `v2` = API v2 add-on (no fallback to standard images). Without it: everything your key allows. Not allowed for your key → `403`. `v1v2`

Request

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

200 · Image metadata including the signed `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 · Missing or invalid `x-api-key`.

{
  "error": "Invalid API key"
}

403 · Plan restriction (feature, format or brand not allowed) or blocked request.

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

404 · No data for the requested path.

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