Car Images API

What comes back

photos (the gallery in the source's own order, photos[0] being the hero), primaryImage (that same hero URL, never null on a 200), galleryCount (how many URLs we actually returned), photoCount (how many the source listing advertises, nullable), galleryComplete (true only when those two agree), listingSource (the scrape source, e.g. "autolist"), listingUrl (the vehicle detail page on the source marketplace), source "carscrape" and the upper-cased vin. A real response for a 2026 Ford F-150 might return three cargurus-hosted JPEGs against photoCount 39 and galleryComplete false. That gap is the thing to build for: size your carousel from galleryCount or photos.length, never from photoCount, and treat galleryComplete false as "there are more behind listingUrl".

curl -sS https://api.vehicles.dev/v1/vehicles/photos/1FTFW3L57TKD09376 \
  -H "Authorization: Bearer $VEHICLES_API_KEY" \
  -H "Accept: application/json"

{
  "galleryComplete": false,
  "galleryCount": 3,
  "listingSource": "autolist",
  "listingUrl": "https://www.autolist.com/ford-f+150#vin=1FTFW3L57TKD09376",
  "photoCount": 39,
  "photos": [
    "https://static.cargurus.com/images/forsale/2026/07/18/07/13/2026_ford_f-150-pic-6182805071162814707-1024x768.jpeg",
    "https://static.cargurus.com/images/forsale/2026/07/18/07/13/2026_ford_f-150-pic-3355019284471120388-1024x768.jpeg",
    "https://static.cargurus.com/images/forsale/2026/07/18/07/13/2026_ford_f-150-pic-8821004417720935512-1024x768.jpeg"
  ],
  "primaryImage": "https://static.cargurus.com/images/forsale/2026/07/18/07/13/2026_ford_f-150-pic-6182805071162814707-1024x768.jpeg",
  "source": "carscrape",
  "vin": "1FTFW3L57TKD09376"
}

The complete parameter table, the response-field dictionary and the per-endpoint error codes live in the reference: full parameter reference for /v1/vehicles/photos/{vin}.

What it is actually built on

The image comes from our listings table, not from a manufacturer or stock-photography library. For a given VIN we select that VIN's best current listing that actually has an image — active listings win, and among those, the most recently ingested one. That means the photo is the real car (or at least the real listing) rather than a studio render of the trim, which is the right trade-off for verification and identity-confirmation flows and the wrong one if you wanted clean marketing imagery. The URLs we return are CDN links owned by the source marketplace; we do not rehost, resize, watermark or proxy them. The route upper-cases the VIN and requires exactly 17 VIN-safe letters or digits; the backing validator also rejects a bad North American check digit. It runs on a 5-second upstream budget — a valid VIN with no matching image 404s with photos_not_found, and because billing is success-only, that costs nothing.

Data source

The listings table. We pick the VIN's best current listing that has an image — active listings win, then the most recently ingested. Image URLs are CDN links owned by the source marketplace and are not rehosted by us.

Route budget

5 s

Billed per

successful lookup, successful responses only

MCP tool

get_vehicle_photos

Limits: what this endpoint will not do

Gallery coverage is partial and you must check it per response. photoCount is the count the SOURCE advertised; galleryCount is how many URLs we can actually serve; galleryComplete is true only when those agree. They disagree in two ordinary cases: the source published a count without exposing the gallery, and the listing was last crawled before gallery capture shipped. Coverage grows as listings are re-crawled, so an empty photos array with a non-zero photoCount means "we do not hold these URLs", never "this car has no photos" — follow listingUrl for the rest. A VIN that appears in Car Listings API results can still 404 here, because the matched listing row may have no primary image; a 404 means "no listing with an image", not "no such vehicle". Lookups are VIN-keyed only: there is no year/make/model image endpoint, so you cannot get a picture of a 2023 Camry XSE in the abstract, only of specific VINs that have appeared in listings we scraped. The URLs point at third-party CDNs and will rot when the underlying listing is taken down — treat them as ephemeral and mirror anything you need to keep, ideally with a fallback in your UI for a 404 on the image itself. Rights in the images belong to the source marketplace or dealer, not to us; we return a pointer, and you should confirm your own use is permitted before republishing. Coverage is US listings only. The endpoint is available now and successful responses use the published catalog rate. Standard plans include no SLA.

What teams build with it

Integrating it properly

The reference ships the bare curl. This is the shape worth deploying: a typed client that branches on the RFC 9457 code slug rather than the human-readable title, and retries only the codes this endpoint marks retryable.

const API = "https://api.vehicles.dev";

// Only these codes are marked retryable for this endpoint. Everything else is terminal.
const RETRYABLE = new Set(["photos_upstream_unavailable", "photos_upstream_error"]);

export async function getVehiclePhotos(vin: string, attempt = 0): Promise<GetVehiclePhotosResponse> {
  const response = await fetch(
    `${API}/v1/vehicles/photos/${encodeURIComponent(vin)}`,
    {
      headers: {
        Accept: "application/json",
        Authorization: `Bearer ${process.env.VEHICLES_API_KEY ?? ""}`
      },
      // The route budget is 5 s; allow it plus headroom.
      signal: AbortSignal.timeout(10_000)
    }
  );

  if (response.ok) return (await response.json()) as GetVehiclePhotosResponse;

  // Failures are application/problem+json. Branch on `code`, never on the human-readable title.
  const problem = (await response.json()) as { code: string; detail?: string };
  if (RETRYABLE.has(problem.code) && attempt < 3) {
    await new Promise((resolve) => setTimeout(resolve, 250 * 2 ** attempt));
    return getVehiclePhotos(vin, attempt + 1);
  }
  throw new Error(`${response.status} ${problem.code}: ${problem.detail ?? ""}`);
}

How to check it is behaving

The route enforces a 5-second upstream budget, so a slow dependency returns a problem document instead of holding your request open. Exactly 2 codes are marked retryable here — photos_upstream_unavailable and photos_upstream_error — and everything else documented for this endpoint is terminal, so backoff on anything else just burns your rate limit. Billing is success-only: failed calls release their reservation, so you can measure error rates and hold-out accuracy against your own data without paying for the failures. Usage is visible per endpoint in the dashboard.

What this one endpoint costs

Priced per successful lookup. The platform fee buys throughput and endpoint access; the unit price covers the data work. Worked at 100,000 successful calls a month so you can see where the plans cross over — the full price matrix is in the reference.

Eligible for the Starter plan's included monthly calls; past those it draws on your credit balance. Data fees are prepaid from credits on every plan: when included calls and credits cannot cover a call you get 402 insufficient_credits rather than an overage bill. Published rates are active and apply only to successful responses. Standard plans include no SLA.

Questions engineers actually ask

Where to go next

Most integrations chain two or three of these. The ones that pair with car images api most often:

• Car Listings APIFilter 1,721,693 normalized US dealer listings by make, model, year, price, mileage and state, and get the total match count alongside the page.
• VIN Decoder APINormalized year, make, model, trim, body and powertrain from a VIN. Verified-store-first, with a live NHTSA vPIC fallback for everything else.
• Vehicle Valuation APIAn ML-predicted current asking price in whole USD for a year/make/model, with the model's 3.7% median holdout error reported on every response.

The reference entry for this endpoint — Vehicle Photos in the API documentation — carries the parameter constraints, defaults, response fields and the full error table with retryable flags. Agents can reach the same endpoint as the get_vehicle_photos tool on the vehicles-dev-mcp MCP server, and the machine-readable contract is published at https://api.vehicles.dev/openapi.json.

Browse the rest of the catalog on the Vehicle data APIs hub.