docs / api / images / vehicle-images

Vehicle Images API

The Vehicle Images API provides programmatic access to high-quality, OEM-style rendered vehicle images. It supports image retrieval using identifiers such as VIN or Spec ID for reports, marketing content, inventory tools, and consumer-facing applications. Optional parameters allow customization by pose, color, background, size, and format, with watermarking support for demo and production use. Both VIN-based and ID-based searches use the same `GET` endpoint, with either `vin` or `id` passed as the required query parameter.

Search by VIN

GET
https://images.vinaudit.com/v3/images

Request Parameters

Parameter

vin

required

Example

1NXBR32E85Z505904

Description

The vehicle identification number

Parameter

key

required

Example

YOUR_API_KEY_HERE

Description

Your VinAudit API key

Parameter

format

optional

Example

html, json, xml (invalid inputs return error)

Description

The output format (default: json)

Parameter

pose

optional

Example

front_left, front_right, front, back_left, back_right, back, right, left

Description

Controls the image/view angle returned (default: front_right)

Parameter

color

optional

Example

white, black, gray (or grey), silver, blue, red, green, brown, beige, gold, orange, purple, yellow

Description

Requests a specific vehicle color (default: white)

Parameter

background

optional

Example

white, gallery

Description

Sets the image background (default: white)

Parameter

size

optional

Example

full

Description

Sets the output image size (default: medium)

Predefined Tiers:

  • small → 640×480 (thumbnail)

  • medium → 1280×960 (default)

  • large → 2048×1536 (marketing, social)

  • xlarge → 3000×2000 (dealership-quality)

  • full → 6000×4000 (print, archival)

  • Custom → Explicit dimensions (e.g., size=1920×1080)

Note: The size parameter is valid only with format=json or format=xml.

Parameter

granularity

optional

Example

trim, model

Description

Controls whether images are generated at the trim or model level (default: trim)

Parameter

crop

optional

Example

true, false

Description

Removes image padding (default: false)

Example Request by VIN

https://images.vinaudit.com/v3/images?vin=5J8TC1H38KL003076&pose=front_right&color=white&background=gallery&key=YOUR_API_KEY_HERE&format=html

Search by ID

GET
https://images.vinaudit.com/v3/images

Request Parameters

Parameter

id

required

Example

2024_maserati_mc20_cielo

Description

Unique identifier associated with one of the following combinations:

  • year_make_model_trim

  • year_make_model_trim_style

Parameter

key

required

Example

YOUR_API_KEY_HERE

Description

Your VinAudit API key

Parameter

format

optional

Example

html, json, xml (invalid inputs return error)

Description

The output format (default: json)

Parameter

pose

optional

Example

front_left, front_right, front, back_left, back_right, back, right, left

Description

Controls the image/view angle returned (default: front_right)

Parameter

color

optional

Example

white, black, gray (or grey), silver, blue, red, green, brown, beige, gold, orange, purple, yellow

Description

Requests a specific vehicle color (default: white)

Parameter

background

optional

Example

white, gallery

Description

Sets the image background (default: white)

Parameter

size

optional

Example

small

Description

Sets the output image size (default: medium)

Predefined Tiers:

  • small → 640×480 (thumbnail)

  • medium → 1280×960 (default)

  • large → 2048×1536 (marketing, social)

  • xlarge → 3000×2000 (dealership-quality)

  • full → 6000×4000 (print, archival)

  • Custom → Explicit dimensions (e.g., size=1920×1080)

Note: The size parameter is valid only with format=json or format=xml.

Parameter

granularity

optional

Example

trim, model

Description

Controls whether images are generated at the trim or model level (default: trim)

Parameter

crop

optional

Example

true, false

Description

Removes image padding (default: false)

Example Request by YMMT ID

https://images.vinaudit.com/v3/images?id=2024_maserati_mc20_cielo&pose=front_right&color=white&background=gallery&key=YOUR_API_KEY_HERE&format=html

Example Successful Response (HTML)

This request uses format=html to return a directly embeddable HTML-rendered vehicle image from either a VIN-based or ID-based request.

2024_maserati_mc20_cielo_front_right.png

Example Request by ID (Custom Resolution)

Request by ID with size=1024x1024 and format=json to return a custom-resolution JSON response:

https://images.vinaudit.com/v3/images?id=2024_maserati_mc20_cielo&color=white&size=1024x1024&key=YOUR_API_KEY_HERE&format=json

Example Response (JSON)

Set format=json to return the following structured response fields:

json
{
  "id": "2024_maserati_mc20_cielo",
  "images": [
    {
      "content_type": "image/png",
      "data": "iVBORw0KGgoAAAANSUhMuAAEAAE..."
    }
  ],
  "success": true,
  "ymmt": {
    "year": "2024",
    "make": "Maserati",
    "model": "MC20",
    "trim": "Cielo"
  }
}

Example Response (XML)

Set format=xml to return the following structured response fields:

xml
<result>
  <id>2024_maserati_mc20_cielo</id>
  <images>
    <record>
      <content_type>image/png</content_type>
      <data>iVBORw0KGgoAAAANSUhMuAAEAAE...</data>
    </record>
  </images>
  <success>1</success>
  <ymmt>
    <year>2024</year>
    <make>Maserati</make>
    <model>MC20</model>
    <trim>Cielo</trim>
  </ymmt>
</result>

Error Response

Returns a JSON object indicating failure:

json
{
  "success": false,
  "error": "Invalid input or unsupported vehicle configuration"
}

Notes

  • The default response is JSON.
  • For json/xml, the API now returns binary/base64 image data instead of URLs (removes API key exposure).
  • HTML remains supported for viewing/debugging purposes.
  • Invalid parameters (pose, format, background, color, size) return descriptive error messages.

System Constraints and Behavior

VIN Resolution VINs must resolve to a valid id (spec ID) in the system.

Granularity The granularity parameter controls whether images are generated at the trim or model level.

• Default behavior is granularity=trim, which generates images using the full resolved specification, including trim.

• When granularity=model, the trim is ignored and a model-level image is generated.

• Multiple trims of the same model return the same image when granularity=model.

• A default trim is selected internally for model-level rendering, currently the most popular available trim, since the Specs API does not expose a base trim.

Crop Removes image padding.

Fallback on Trims If the requested trim does not exist, API returns images for an available trim of the same model.

Background Defaults to white unless specified.

Resolution Support Validated from small (640×480) up to full (6000×4000), plus custom sizes.

Concurrency Multiple workers confirmed to handle concurrent requests.

Batch Limitation Only single-image requests are supported per API call.

Ping Endpoint Use this health-check endpoint to confirm the image service is reachable:

https://images.vinaudit.com/ping

Ready to build?

Access the Vehicle Images API with a free developer account. No credit card required.

Start Free TrialView API Docs