---
title: "Vehicle Images"
description: "Retrieve photos of any vehicle by make, model, and year — filter by angle, color, and size."
canonical_url: "https://docs.carsxe.com/docs/products/vehicle-images"
markdown_url: "https://docs.carsxe.com/docs/products/vehicle-images.md"
last_updated: "1980-01-01"
x_farming_labs_generated_preamble: true
agent:
  task: "Retrieve vehicle stock images from CarsXE by VIN or YMM. Related:"
  outcome: "A Vehicle Images request returns the documented successful vehicle-data response for the supplied input."
  prerequisites:
    - "A valid CarsXE API key with access to this endpoint."
    - "The vehicle identifier or request inputs required by the Vehicle Images example."
  verification:
    - "Run one documented Vehicle Images request and confirm the response is successful and contains the fields described on this page."
  failureModes:
    - symptom: "The Vehicle Images request is rejected or does not return the expected data."
      resolution: "Check the API key, plan access, supported input format, and the returned status code against the error guide before retrying."
---

# Vehicle Images
URL: /docs/products/vehicle-images
LLM index: /llms.txt
Description: Retrieve photos of any vehicle by make, model, and year — filter by angle, color, and size.
Related: /docs/products, /docs/get-started

<!-- farming-labs:agent-contract:start -->
## Agent Contract

Task: Retrieve vehicle stock images from CarsXE by VIN or YMM. Related:
Outcome: A Vehicle Images request returns the documented successful vehicle-data response for the supplied input.

### Prerequisites

- A valid CarsXE API key with access to this endpoint.
- The vehicle identifier or request inputs required by the Vehicle Images example.

### Verification

- Run one documented Vehicle Images request and confirm the response is successful and contains the fields described on this page.

### Failure Modes

- The Vehicle Images request is rejected or does not return the expected data. — Recovery: Check the API key, plan access, supported input format, and the returned status code against the error guide before retrying.
<!-- farming-labs:agent-contract:end -->

Task: Retrieve vehicle stock images from CarsXE by VIN or YMM. Related:
  /docs/products/vehicle-images, /docs/products/specifications,
  /docs/get-started

Fetch real vehicle photos for any make and model. Returns up to 10 clean, relevant results per call. Filter by angle, color, photo type, and size to get exactly the images your use case needs.

## Who uses this API

Dealerships, rental platforms, and marketplaces call this endpoint when they need stock photos for a year, make, and model — especially when the lot has no shoot yet.

## Use cases

### B2B

- **Dealerships — listing photos:** Fill a VDP with front, side, or rear images when a unit has no photography yet.
- **Rental — catalog visuals:** Show a consistent make/model photo on booking pages without photographing every unit.
- **Marketplaces — placeholder galleries:** Attach representative images to a listing until seller photos are uploaded.

### B2C

- **Consumer listing galleries:** Show make/model photos on a private-party listing while the seller adds their own shots.
- **Comparison tools:** Display matching angles across vehicles a shopper is comparing.

## Parameters

| Parameter     | Required | Description                                                                                       |
| ------------- | -------- | ------------------------------------------------------------------------------------------------- |
| `make`        | Yes      | Vehicle manufacturer. Example: `"Toyota"`, `"Ford"`, `"BMW"`                                      |
| `model`       | Yes      | Vehicle model name. Example: `"Camry"`, `"F-150"`, `"3 Series"`                                   |
| `key`         | Yes      | Your CarsXE API key                                                                               |
| `year`        | No       | 4-digit model year. Narrows results to a specific model year                                      |
| `trim`        | No       | Trim level. Helps surface images of the right variant                                             |
| `color`       | No       | Preferred vehicle color. Example: `"red"`, `"midnight blue"`                                      |
| `angle`       | No       | `front`, `side`, or `back`                                                                        |
| `photoType`   | No       | `interior`, `exterior`, or `engine`. Only valid alongside `make`, `model`, `year`, and `trim`     |
| `size`        | No       | `Small`, `Medium`, `Large`, `Wallpaper`, or `All`                                                 |
| `license`     | No       | Usage-rights preset, or a comma-separated list of specific license tokens. See [Usage rights](#usage-rights). |
| `transparent` | No       | `true` (default) — prefer images with transparent/white backgrounds                               |
| `validate`    | No       | `true` (default) — return only clean, relevant vehicle photos                                     |
| `format`      | No       | `json` (default) or `xml`                                                                         |

## Example

<CodeGroup title="Get vehicle images" tag="GET" label="/images">

```bash
curl -G https://api.carsxe.com/images \
  -d key=YOUR_API_KEY \
  -d make=Toyota \
  -d model=Camry \
  -d year=2022 \
  -d angle=front
```

```js
import { CarsXE } from "carsxe-api";

const carsxe = new CarsXE("YOUR_API_KEY");
const make = "Toyota";
const model = "Camry";
const year = "2022";
const angle = "front";

try {
  const images = await carsxe.images({ make, model, year, angle });
  console.log(images);
} catch (error) {
  console.error(error);
}
```

```python
import asyncio
from carsxe_api import CarsXE

carsxe = CarsXE("YOUR_API_KEY")
make = "Toyota"
model = "Camry"
year = "2022"
angle = "front"

try:
    images = asyncio.run(carsxe.images({"make": make, "model": model, "year": year, "angle": angle}))
    print(images)
except Exception as e:
    print(f"Error: {e}")
```

```php
<?php
require_once __DIR__ . '/vendor/autoload.php';
use CarsxeDeveloper\Carsxe\Carsxe;

$carsxe = new Carsxe("YOUR_API_KEY");
$make = "Toyota";
$model = "Camry";
$year = "2022";
$angle = "front";

try {
    $images = $carsxe->images(["make" => $make, "model" => $model, "year" => $year, "angle" => $angle]);
    print_r($images);
} catch (Exception $error) {
    echo "Error: " . $error->getMessage();
}
```

```ruby
require "carsxe"

carsxe = Carsxe::CarsXE.new(api_key: "YOUR_API_KEY")
make = "Toyota"
model = "Camry"
year = "2022"
angle = "front"

begin
  images = carsxe.images("make" => make, "model" => model, "year" => year, "angle" => angle)
  puts images
rescue StandardError => error
  puts "Error: #{error.message}"
end
```

```go
package main

import (
	"fmt"
	"github.com/carsxe/carsxe-go-package"
)

func main() {
	client := carsxe.New("YOUR_API_KEY")
	make := "Toyota"
	model := "Camry"
	year := "2022"
	angle := "front"
	images := client.Images(map[string]string{"make": make, "model": model, "year": year, "angle": angle})
	fmt.Println(images)
}
```

```java
import io.github.carsxe.CarsXE;
import java.util.Map;
import java.util.HashMap;

public class Main {
    public static void main(String[] args) {
        CarsXE carsxe = new CarsXE("YOUR_API_KEY");
        Map<String, String> params = new HashMap<>();
        params.put("make", "Toyota");
        params.put("model", "Camry");
        params.put("year", "2022");
        params.put("angle", "front");

        try {
            Map<String, Object> images = carsxe.images(params);
            System.out.println(images);
        } catch (Exception e) {
            System.err.println("Error: " + e.getMessage());
        }
    }
}
```

```swift
import carsxe

let carsxe = CarsXE(apiKey: "YOUR_API_KEY")
let make = "Toyota"
let model = "Camry"
let year = "2022"
let angle = "front"

do {
    let images = try carsxe.images(["make": make, "model": model, "year": year, "angle": angle])
    print(images)
} catch {
    print("Error: \(error)")
}
```

```csharp
using carsxe;
using System;
using System.Collections.Generic;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        CarsXE carsxe = new CarsXE("YOUR_API_KEY");
        string make = "Toyota";
        string model = "Camry";
        string year = "2022";
        string angle = "front";

        try
        {
            var images = await carsxe.Images(new Dictionary<string, string> { { "make", make }, { "model", model }, { "year", year }, { "angle", angle } });
            Console.WriteLine(images);
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Error: {ex.Message}");
        }
    }
}
```

```bash {{ title: "Response" }}
{
  "success": true,
  "query": {
    "make": "Toyota",
    "model": "Camry",
    "year": "2022",
    "angle": "front"
  },
  "images": [
    {
      "mime": "image/jpeg",
      "link": "https://example.com/toyota-camry-2022-front.jpg",
      "contextLink": "https://example.com/toyota-camry-2022",
      "height": "1080",
      "width": "1920",
      "byteSize": 245760,
      "thumbnailLink": "https://encrypted-tbn0.gstatic.com/images?q=...",
      "thumbnailHeight": "168",
      "thumbnailWidth": "300"
    },
    {
      "mime": "image/jpeg",
      "link": "https://example.com/2022-camry-exterior.jpg",
      "contextLink": "https://example.com/2022-camry-review",
      "height": "720",
      "width": "1280",
      "byteSize": 184320,
      "thumbnailLink": "https://encrypted-tbn0.gstatic.com/images?q=...",
      "thumbnailHeight": "112",
      "thumbnailWidth": "200"
    }
  ]
}
```

</CodeGroup>

## Response

### Top-level shape

<VehicleImagesTopLevelShape />

Click the `query` or `images` sections to expand them and see sample data. For the full interactive reference, try it live in the [API Reference](/api-reference).

The `images` array is always present. It will be empty when no matching images are found — not absent.

### images

Each object in the `images` array represents one vehicle photo.

<Properties>
  <Property name="mime" type="string">
    The MIME type of the image file. Example: `"image/jpeg"`, `"image/png"`,
    `"image/webp"`.
  </Property>
  <Property name="link" type="string">
    Direct URL to the full-resolution image. Use this to display or download the
    image.
  </Property>
  <Property name="contextLink" type="string">
    Related page URL for the image — useful for attribution.
  </Property>
  <Property name="height" type="string | number">
    Image height in pixels. May be returned as a string or number depending on
    the image.
  </Property>
  <Property name="width" type="string | number">
    Image width in pixels. May be returned as a string or number depending on
    the image. All images are at least 300px on their shortest side.
  </Property>
  <Property name="byteSize" type="number | string">
    File size in bytes. Useful for estimating download time or enforcing size
    limits before fetching the full image.
  </Property>
  <Property name="thumbnailLink" type="string">
    URL to a smaller thumbnail of the image. Faster to load than the full image
    — useful for previews and grids.
  </Property>
  <Property name="thumbnailHeight" type="string">
    Thumbnail height in pixels.
  </Property>
  <Property name="thumbnailWidth" type="string">
    Thumbnail width in pixels.
  </Property>
</Properties>

## Usage rights

`license` filters results by Creative Commons labels that the hosting site attached to the image. It does not grant a copyright license. Every image includes a `contextLink` to the source page. Confirm the license there before you download, publish, or reuse the photo.

Leave `license` blank to return images regardless of license label. An unknown token returns `400`.

### Presets

| Value                 | Meaning                                              | Included labels                                      | Excluded labels                    |
| --------------------- | ---------------------------------------------------- | ---------------------------------------------------- | ---------------------------------- |
| `Public`              | Public domain only                                   | `cc_publicdomain`                                    | —                                  |
| `Share`               | Free to use or share                                 | Public domain, attribution, ShareAlike, NonCommercial, NoDerivatives | —                       |
| `ShareCommercially`   | Free to use or share, even commercially              | Public domain, attribution, ShareAlike, NoDerivatives | NonCommercial                     |
| `Modify`              | Free to use, share, or modify                        | Public domain, attribution, ShareAlike, NonCommercial | NoDerivatives                     |
| `ModifyCommercially`  | Free to use, share, or modify, even commercially     | Public domain, attribution, ShareAlike               | NonCommercial, NoDerivatives       |

### Specific licenses

Pass one or more tokens instead of a preset. Separate them with commas. Prefix a token with `-` to exclude images that carry that label. Include at least one token. A token cannot be both included and excluded.

| Token               | Label                    | Meaning                                                                                          |
| ------------------- | ------------------------ | ------------------------------------------------------------------------------------------------ |
| `cc_publicdomain`   | Public domain            | No copyright-license conditions on the labeled work.                                            |
| `cc_attribute`      | Attribution (BY)         | Use, including commercially, and modify. Credit the creator when you share the work.           |
| `cc_sharealike`     | ShareAlike (SA)          | Modifications are allowed. If you share an adaptation, use the same license.                   |
| `cc_noncommercial`  | NonCommercial (NC)       | Commercial use is not allowed.                                                                   |
| `cc_nonderived`     | NoDerivatives (ND)       | Sharing a modified version is not allowed.                                                       |

`ModifyCommercially` is equivalent to `cc_publicdomain,cc_attribute,cc_sharealike,-cc_noncommercial,-cc_nonderived`.

To request public-domain and attribution-only images, excluding ShareAlike, NonCommercial, and NoDerivatives:

```bash
curl -G https://api.carsxe.com/images \
  -d key=YOUR_API_KEY \
  -d make=Toyota \
  -d model=Camry \
  -d license=cc_publicdomain,cc_attribute,-cc_sharealike,-cc_noncommercial,-cc_nonderived
```

## Image quality

<Note>
  By default (`validate=true`), results include only clean, relevant vehicle
  photos that match the requested make, model, and year.

  Pass `validate=false` for up to 10 images at full speed.
</Note>

## Errors

See the [Errors guide](/docs/guides/errors) for the full list. The most common cases specific to this endpoint:

- **400** — `"Invalid license..."` — `license` is not a preset or a comma-separated list of the tokens above. Fix the value and retry.
- **500** — `"Please supply a make and model..."` — both parameters are required. Add them and retry. Branch on the `success` field.
- **404** — No images found for this combination — try relaxing your filters (remove `angle`, `color`, or `trim`) or verify the make and model spelling.

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).
