Car Image API
Documentation

Images

GET /api/v1/images/car — parameters, headers, JSON mode.

GET/api/v1/images/car
images:read1 credit

Query parameters

GET /api/v1/images/car parameters
ParameterTypeDescription
makerequired
string
Manufacturer as it appears in the catalog. Case, spaces and punctuation are normalized ("Mercedes-Benz", "mercedes benz" and "mercedes-benz" are the same make).
modelrequired
string
Model name, normalized the same way ("model-3", "Model 3"). A unique prefix also resolves.
yearrequired
integer
Model year between 1990 and next year. Must exist for the make/model in the catalog.
viewrequired
front | front-3-4 | side | side-right | rear | rear-3-4
Camera angle. Aliases such as hero, front34, profile and back are accepted. See Views & sizes.
color
enum
One of 15 preset paint colors: white, black, gray, silver, blue, red, green, brown, beige, tan, orange, yellow, gold, burgundy, purple.Default: silver
size
thumb | small | medium | large
Named width preset (thumb=256, small=512, medium=768, large=1024). Ignored when w or h is given.
w
integer 1–1024
Target width in pixels. The source is square, so the output fits inside w×h.
h
integer 1–1024
Target height in pixels.
format
png | webp | jpg
Output encoding. PNG and WebP keep the transparent background; JPG gets a flat one.Default: png

Example

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&view=front-3-4&color=red" \
  --output porsche-911.png

Equivalent spellings of a vehicle map to one cache entry, so Porsche and porsche cost the same and hit the same image.

Response

200 OK with the image bytes and a Content-Type of image/png, image/webp or image/jpeg. Metadata travels in headers:

HeaderExampleMeaning
X-Credits-Charged1Credits debited for this response — always 1 for a delivered image.
X-Credits-Remaining4870Balance after the debit. Plan top-ups before it reaches 0.
X-Image-Sourcecache | generatedCDN hit or cold render. Same price either way.
X-Image-Width1024Delivered width in pixels.
X-Image-Height1024Delivered height in pixels.
ETag"9f2a…c41d"Stable per image variant. Send If-None-Match to receive a free 304.
Cache-Controlprivate, no-storeBilled responses bypass HTTP caches. Store bytes explicitly and use ETags, or mint a cacheable signed URL for embeds.
X-Request-Idreq_01j9x…Include it in bug reports and feedback.

JSON mode: get a signed URL instead of bytes

Send Accept: application/json and the endpoint returns a signed delivery URL instead of the image. This is handy for agents and for servers that pass images to a browser without proxying bytes. Billing is unchanged: one credit.

bash
curl -H "Authorization: Bearer $CAR_IMAGE_API_KEY" \
  -H "Accept: application/json" \
  "https://carimage.dev/api/v1/images/car?make=porsche&model=911&year=2024&view=front-3-4&color=red"
200 OK
{
  "data": {
    "url": "https://carimage.dev/api/v1/delivery/eyJhbGciOi…",
    "expires_at": "2026-09-02T18:00:00.000Z",
    "max_uses": 0,
    "vehicle": {
      "make": "porsche",
      "model": "911",
      "year": 2024,
      "view": "front-3-4",
      "color": "red"
    },
    "width": 1024,
    "height": 1024,
    "source": "cache"
  },
  "billing": {
    "credits_charged": 1,
    "credits_remaining": 4870
  },
  "request_id": "req_01j9x…"
}

Conditional requests

Store the ETag with the bytes. On the next request send it as If-None-Match: a matching variant returns 304 Not Modified with no body and no charge.

bash
curl -I -H "Authorization: Bearer $CAR_IMAGE_API_KEY" \
  -H 'If-None-Match: "9f2a…c41d"' \
  "https://carimage.dev/api/v1/images/car?make=porsche&model=911&year=2024&view=front-3-4&color=red"
# HTTP/2 304

Cold renders and refunds

When a make/model/year/color/view combination has never been requested, the API renders it synchronously (up to two minutes) and saves it in a private origin. New images start at low quality; popular images are upgraded in the background while the current image remains available. Concurrent requests share one generation; each delivered image still costs one credit. If rendering fails the request returns 502 and the credit is refunded.

Errors

  • 400 — a parameter is missing or invalid (the detail says which).
  • 401 — missing, revoked or malformed key.
  • 402 — fewer than 1 credit left. Do not retry; top up.
  • 404 — the vehicle is not in the catalog for that year.
  • 429 — rate limited; wait Retry-After seconds.
  • 502 — the render failed; refunded.

Every failure is application/problem+json. See Errors.