Car Image API quickstart

One call, your first image in two minutes.

1. Get an API key

Sign in and you start with 100 free credits — no card. The dashboard opens on your first key, already filled into a request you can run from the page. Or let the CLI make one through a browser-approved device code:

bash

npx @meterapp/car-image login

Keys belong in headers or your environment

A key is shown once and stored as a hash: keep it in CAR_IMAGE_API_KEY on a server, never in a URL, a prompt or a committed config. Scopes, the device flow and OAuth for agents are in Authentication.

2. Request an image

One call, three parameters: make, model and year name any vehicle in the catalog. Add view for one of eight camera angles and color for any paint when you need them.

Building a web page? Start with the HTML and React examplesbelow: create a signed URL for the browser. Use the byte request here when you want to download a file.

bash

curl --fail-with-body \
  -H "Authorization: Bearer $CAR_IMAGE_API_KEY" \
  "https://carimage.dev/api/v1/images/car?make=porsche&model=911&year=2024" \
  --output porsche-911.png

The bytes come back in the response: the first render of a vehicle nobody has requested takes about 20 seconds, and every later request for it is one credit, served from cache.

3. Read the response headers

Every image response says what it cost and where it came from:

Header	Example	Meaning
`X-Credits-Remaining`	99	Your balance after this request.
`X-Image-Source`	cache	cache (a saved render) or generated (a cold render); the price is the same 1 credit.
`ETag`	"9f2a…c41d"	Send it back as If-None-Match: an unchanged image answers 304 and costs nothing.
`X-Request-Id`	req_01j…	Quote it when you write to support.

4. Show the image in HTML or React

A signed delivery URL works as an ordinary image source in HTML and React. No browser SDK is needed. Your server or build step creates it with POST /api/v1/image-urls; only the returned data[0].url reaches the page. Look the vehicle up first and store its vehicle id.

Server or build step · create the URL once

curl --fail-with-body \
  -X POST https://carimage.dev/api/v1/image-urls \
  -H "Authorization: Bearer $CAR_IMAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: listing-911-hero-v1" \
  -d '{"images":[{"vehicle":"veh_78qtwrgh37bkr","view":"front-3-4","width":600,"height":400,"trim":true,"format":"auto"}],"ttl_seconds":604800}'

HTML · paste the returned URL

<!-- Replace SIGNED_DELIVERY_URL with the complete data[0].url from your server. -->
<img
  src="SIGNED_DELIVERY_URL"
  alt="2024 Porsche 911, front three-quarter view"
  width="600" height="400"
  loading="lazy" decoding="async"
  style="max-width: 100%; height: auto;"
>

React · pass the returned URL as a prop

// Pass the complete data[0].url from your server as src.
// Works in React, including Vite apps and Next.js Client Components.
export function CarImage({ src, alt }: { src: string; alt: string }) {
  return (
    <img
      src={src} alt={alt}
      width={600} height={400}
      loading="lazy" decoding="async"
      style={{ maxWidth: "100%", height: "auto" }}
    />
  );
}

// deliveryUrl is the signed URL your server returned and stored.
<CarImage src={deliveryUrl} alt="2024 Porsche 911, front three-quarter view" />

Keep the API key on the server. Reuse the URL; do not mint during React client rendering or in a browser effect. One URL costs one credit to create; repeated loads are free until expires_at. This example requests a seven-day lifetime. Replace it before expiry, or choose auto-renewal for longer-lived pages (one more credit per opened renewal window). Set image options when creating the URL; use the returned URL unchanged.

For server-side minting, caching and placeholders, follow the React and Next.js guide. For static HTML, follow Pages without a backend.

5. Pick your guide

Reference: Authentication · Images · Signed URLs · Vehicles & search · Errors

Integrations: React & Next.js · Shopify · WordPress.