Vehicle Imagery API v1.2.0

Studio-quality car images for every make, model, year, variant, trim and view — delivered as signed CDN URLs with on-the-fly format, size, aspect-ratio, paint color, shadow, transparency, grounding and floor-mirroring.

Base URL

All endpoints live under https://api.vehicleimagery.com.

Authentication

Every request needs your API key in the x-api-key header:

curl -H "x-api-key: YOUR_API_KEY" https://api.vehicleimagery.com/api/brands

What your key may do (formats, ratios, features, brands) is returned by /api/me. The docs endpoints (/api/openapi.json, /api/docs) are public and need no key.

How it works

1. Navigate the catalog down to one car: brand → model → year → variant → trim → view, e.g. GET /api/Abarth/124_Spider_Abarth/2016/Basis/base.
2. Resolve an image by adding the view + options: GET /api/Abarth/124_Spider_Abarth/2016/Basis/base/front_left?format=webp&width=1200 → returns metadata plus a signed image_url.
3. Embed image_url straight into your <img>. It is signed and transform-locked; the bytes are generated on first request and cached on the CDN for your plan's TTL (default 7 days).

API v2 add-on: studio sets, 360° spins and lifestyle *(new)*

Keys with the API v2 add-on also get our new studio image sets — in the same catalog and with the same calls. Check access in /api/me: v1 = standard images, v2 = add-on, all = both. On the trim endpoint a car with add-on images lists groups next to views:

• Standard views (front, front_left … right) — same URLs as always.
• Studio groups — …/{trim}/{group} lists the images, …/{trim}/{group}/{image} resolves one:
• hero — hero shots, three-quarter views, some from ground level (8 images)
• steered — front wheels turned, from three camera heights (8 images)
• extra — more angles: every side and corner from eye level, high and low, corners also at 30° and 45° (56 images)
• drone — from above: angled shots, steep views and straight from the top (7 images)
• Image names say where the camera is: the side (front, front_left, left, rear_right …) plus _eye (eye level), _high (above), _low (low), _ground (at ground level), _30 / _45 (corner view at 30° / 45°), _steep (steep from above) or top (straight down). Numbers per car can differ; /api/getall and the group endpoint show them.
• 360° spins — …/{trim}/360 lists the rings (eye_level, low, high), …/{trim}/360/{ring} returns every frame with its own image_url (a spin needs all of them, in order).
• Lifestyle scenes — …/{trim}/lifestyle lists the scenes, …/lifestyle/{scene} their images, …/lifestyle/{scene}/{image} resolves one.

Every reference endpoint knows the add-on: /api/search and /api/getall include add-on cars (getall with their groups), a car's /colors, /features and /all describe its add-on options, and /api/options, /api/sizes, /api/views and /api/me add an addon section. Everything also works by stable id (/api/id/{id}/…).

Add-on images take extra options: lights, background (white, transparent or any hex), color as hex (e.g. c8102e), windows=dark, plate (blank or your logo), fit, size and hotspots — see *Resolve a signed image URL*. Without the add-on these parameters are ignored and no groups are listed.

Names & ids: all cars, standard and add-on, use the same catalogue naming (e.g. Mercedes-Benz / C-Class, BMW / 5 series). Names used before 5 October 2026 (e.g. Mercedes / C-Klasse) still resolve and answer with the current name. Names never contain a slash: where the catalogue writes one, the name has a hyphen (e.g. Chevrolet / C-K). Cars that exist only in the add-on have ids from 900000000; /api/id/{id}/… works for them like for every other car.

Have a real vehicle? *(Beta)*

If you know the car's VIN or registration number instead of its catalogue position, the lookup add-ons do both steps in one call: GET /vin/{vin} and GET /plate/{plate} decode the vehicle and return the closest catalogue match with signed image URLs alongside the decoded data. Both are opt-in per key — check features.vin and features.plate in /api/me; without the add-on they return 403.

Image options

Append to any image request: format, resolution, ratio, width, height, quality, color, shadow, transparency, ground, mirroring. All options combine freely (e.g. ?color=wine_red&shadow=true&format=webp&width=1200). The full plan-filtered set is in /api/options.

Paint colors

Cars can be repainted on demand — reflections, chrome, glass and interior stay untouched; only the paint changes, true to its finish (solid or metallic). /api/colors lists the whole catalog as { color_name, color_make } pairs: the house colors (black, white, blue, orange, wine_red — color_make: "Vehicleimagery") are available on every car; brand colors (e.g. Kia *Racing Red*) belong to cars of that brand. A car's own /colors endpoint lists what is shown for it (house colors + its brand's colors) — any active catalog color can still be requested on any car via ?color=. Details: the *Paint colors* guide at /info/guides/colors.

Shadows, transparency & compositing

Studio ground shadows (shadow=true), transparent cut-outs (transparency=true) and opaque white delivery are produced at delivery time for every exterior view — availability is uniform across the whole catalog.

Errornotes (non-fatal)

When a request can't be served *exactly*, the API does not fail — it falls back to the closest valid value and adds a short code to the errornotes array (e.g. Y01 = nearest year used, S05 = shadow unavailable). The full list is in /api/errornotes.

Image delivery & caching

The returned image_url points at the CDN, carries a signature plus an expiry, and is locked to the exact transform — clients can't tamper with it. The first request produces and caches the bytes; every later request is served straight from cache. Just drop the URL into an <img src>.

New images are produced in a fair queue: plans with a higher priority go first, and identical requests that arrive at the same time are produced once. The first load of a new combination usually takes a few seconds; the response header X-Cache tells you where it came from (MISS = just produced, HIT / HIT-R2 = cache, ORIGINAL = untouched source file), X-Queue-Wait-Ms how long it waited. If a very large number of new images is being produced at once, an image URL can answer 503 busy with Retry-After: 5 — just load it again a few seconds later.

Status codes

• 200 — success. Always check errornotes for silent fallbacks.
• 401 — missing or invalid x-api-key.
• 403 — your plan doesn't allow the requested feature, format or brand.
• 404 — no data for that path. The message names exactly what to check.
• 503 — (image URLs only) many new images are being produced right now; retry after the seconds in Retry-After.

Conventions

• Brand / model / variant / trim names are case-insensitive and accept common aliases.
• Years snap to the nearest available generation.
• Catalog endpoints return JSON; image bytes come only from the signed image_url.