API Reference v1

Documentation

Everything you need to integrate studio-quality vehicle imagery into your application.

Home / Documentation

/ authentication /

API Key Authentication

All API requests require an API key sent via the x-api-key header. You can obtain your key through our dashboard or by contacting sales.

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

Keep your API key secret. Never expose it in client-side code. Use server-side requests or a proxy to keep your key secure.

/ base url /

Base URL

All API endpoints are accessed relative to the following base URL:

api.vehicleimagery.com

All responses are returned as JSON with Content-Type: application/json. CORS is enabled for all origins.

/ parameters /

Global Query Parameters

These parameters can be appended to most endpoints to filter results.

Parameter Default Description
format png Image format. Available options depend on your plan.
resolution default Image resolution. Higher resolutions may require a higher-tier plan.
color default Vehicle color. Only used on the image endpoint.
shadow false Add ground shadow to the image. Requires plan permission.
transparency false Return image with transparent background. Requires plan permission.

/ data model /

API Hierarchy

The Vehicle Imagery API follows a hierarchical structure. Navigate step-by-step from brand to image:

Brands → Models → Years → Variants → Trims → Views / Colors / Features → Image
GET /api/brands

List Brands

Returns all available vehicle brands in the database.

Query Parameters

format = png Image format filter (png, webp, etc.)
resolution = default Resolution filter (default, high, etc.)

Example Response

response.json 
{
  "brands": [
    "Audi",
    "BMW",
    "Mercedes-Benz",
    "Volkswagen",
    ...
  ]
}
GET /api/{brand}

List Models

Returns all available models for a given brand.

Path Parameters

brand string Brand name (e.g. BMW, Audi)

Query Parameters

format = png Image format filter
resolution = default Resolution filter

Example Response

response.json 
{
  "brand": "BMW",
  "resolution": "default",
  "format": "png",
  "models": [
    "1 Series",
    "3 Series",
    "X5",
    ...
  ]
}
GET /api/{brand}/{model}

List Years

Returns all available model years for a specific brand and model combination.

Path Parameters

brand string Brand name
model string Model name (e.g. X5, A4)

Query Parameters

format = png Image format filter
resolution = default Resolution filter

Example Response

response.json 
[{
  "brand": "BMW",
  "model": "X5",
  "resolution": "default",
  "format": "png",
  "years": [2020, 2021, 2022, 2023, 2024]
}]
GET /api/{brand}/{model}/{year}

List Variants

Returns all body variants (e.g. Sedan, SUV, Wagon) available for a specific model year.

Path Parameters

brand string Brand name
model string Model name
year number Model year (e.g. 2024)

Query Parameters

format = png Image format filter
resolution = default Resolution filter

Example Response

response.json 
[{
  "brand": "BMW",
  "model": "X5",
  "year": 2024,
  "resolution": "default",
  "format": "png",
  "variants": ["SUV"]
}]
GET /api/{brand}/{model}/{year}/{variant}

List Trims

Returns all available trims for a specific variant.

Path Parameters

brand string Brand name
model string Model name
year number Model year
variant string Body variant (e.g. SUV, Sedan)

Query Parameters

format = png Image format filter
resolution = default Resolution filter

Example Response

response.json 
[{
  "brand": "BMW",
  "model": "X5",
  "year": 2024,
  "variant": "SUV",
  "resolution": "default",
  "format": "png",
  "trims": ["xDrive40i", "M60i"]
}]
GET /api/{brand}/{model}/{year}/{variant}/{trim}

List Views

Returns all available camera angles/views for a specific vehicle configuration. Views marked as "not_allowed" are not included in your current plan.

Path Parameters

brand string Brand name
model string Model name
year number Model year
variant string Body variant
trim string Trim level

Query Parameters

format = png Image format filter
resolution = default Resolution filter

Example Response

response.json 
[{
  "id": "a1b2c3d4e5f6",
  "brand": "BMW",
  "model": "X5",
  "year": 2024,
  "variant": "SUV",
  "trim": "xDrive40i",
  "resolution": "default",
  "format": "png",
  "views": {
    "front": true,
    "front-left": true,
    "side-left": true,
    "rear": true,
    "cockpit": "not_allowed"
  }
}]
GET /api/{brand}/{model}/{year}/{variant}/{trim}/colors

List Colors

Returns all available colors for a specific vehicle configuration. Only colors allowed by your plan are included.

Path Parameters

brand string Brand name
model string Model name
year number Model year
variant string Body variant
trim string Trim level

Query Parameters

format = png Image format filter
resolution = default Resolution filter

Example Response

response.json 
[{
  "id": "a1b2c3d4e5f6",
  "brand": "BMW",
  "model": "X5",
  "year": 2024,
  "variant": "SUV",
  "trim": "xDrive40i",
  "resolution": "default",
  "format": "png",
  "colors": ["default", "Blue", "Black", "White", "Silver"]
}]
GET /api/{brand}/{model}/{year}/{variant}/{trim}/features

List Features

Returns available image features (shadow, transparency) for a configuration. Features marked "not_allowed" are not included in your plan.

Path Parameters

brand string Brand name
model string Model name
year number Model year
variant string Body variant
trim string Trim level

Query Parameters

format = png Image format filter
resolution = default Resolution filter

Example Response

response.json 
[{
  "id": "a1b2c3d4e5f6",
  "brand": "BMW",
  "model": "X5",
  "year": 2024,
  "variant": "SUV",
  "trim": "xDrive40i",
  "resolution": "default",
  "format": "png",
  "features": {
    "shadow": true,
    "transparent": true,
    "shadow_and_transparent": true
  }
}]
GET /api/{brand}/{model}/{year}/{variant}/{trim}/{view}

Get Image

Returns a signed CDN URL for a specific vehicle image. This is the main endpoint for retrieving vehicle imagery. The returned URL is valid for 7 days by default.

Path Parameters

brand string Brand name
model string Model name
year number Model year
variant string Body variant
trim string Trim level
view string Camera angle (e.g. front, front-left, side-left, rear, cockpit)

Query Parameters

format = png Image format (png, webp)
resolution = default Image resolution
color = default Vehicle color (e.g. Blue, Black, White)
shadow = false Include ground shadow (plan-dependent)
transparency = false Transparent background (plan-dependent)

Example Response

response.json 
[{
  "id": "a1b2c3d4e5f6",
  "brand": "BMW",
  "model": "X5",
  "year": 2024,
  "variant": "SUV",
  "trim": "xDrive40i",
  "view": "front-left",
  "resolution": "default",
  "format": "png",
  "settings": {
    "color": "Blue",
    "shadow": true,
    "transparency": false,
    "watermark": false
  },
  "image_url": "https://cdn.vehicle.pics/v1/png/default/BMW/X5/...",
  "errornotes": []
}]
GET /api/resolutions

List Resolutions

Returns all available image resolutions. Filtered by your plan permissions.

Example Response

response.json 
{
  "resolutions": ["default", "high", "ultra"]
}
GET /api/formats

List Formats

Returns all available image formats. Filtered by your plan permissions.

Example Response

response.json 
{
  "formats": ["png", "webp"]
}
GET /api/getall

Get All Configurations

Returns every vehicle configuration in the database, expanded by year. Requires special "getall" permission on your API key. Useful for building local caches or catalogs.

Example Response

response.json 
[
  {
    "brand": "BMW",
    "model": "X5",
    "variant": "SUV",
    "trim": "xDrive40i",
    "year": 2024,
    "resolution": "default",
    "format": "png",
    "color": "default"
  },
  ...
]

/ reference /

HTTP Status Codes

The API uses standard HTTP status codes. Every error response includes a JSON body with an error field describing the issue.

Code Description
401 Missing x-api-key header. Include your API key in the request.
403 Invalid API key, expired key, or the requested resource is not allowed by your plan.
404 The requested brand, model, year, variant, trim, view, or color was not found.
400 Invalid request parameter (e.g. non-numeric year).
500 Internal server error. Contact support if this persists.

Error Notes (Fallback Codes)

When the API can't fulfill your exact request but finds a suitable fallback, it returns the image along with an errornotes array explaining what was changed. This only applies when fallbacks are enabled in your plan.

Code Description
P11 Requested format or resolution not allowed by plan — automatically fell back to your plan default.
F04 Requested color not found — fell back to default color.
C09 Requested color blocked by plan — fell back to default color.
R08 Requested resolution not available for this car — fell back to nearest allowed resolution.
S05 Shadow requested but not available or not allowed — returned without shadow.
S12 Non-shadow version not available — shadow version returned instead.
T06 Transparency requested but not available or not allowed — returned without transparency.
T13 Non-transparent version not available — transparent version returned instead.

Rate Limits & Caching

Rate limits depend on your plan. All image URLs are served through a global CDN and signed with a time-limited token (default 7 days). Cache these URLs on your end for optimal performance.

50ms

Avg. Latency

99.99

Uptime SLA

7 Days

URL Expiry

Ready to get started?

Get your API key and start integrating studio-quality vehicle imagery today.

Get API Key Contact Sales