Vehicle Imagery API v1.1.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).

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 renders and caches the bytes; every later request is served straight from cache. Just drop the URL into an <img src>.

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.

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.