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.

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.
`shadow`	string	Studio ground shadow — rendered 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`

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