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
Parameter	Type	Description
`make`required	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).
`model`required	string	Model name, normalized the same way ("model-3", "Model 3"). A unique prefix also resolves.
`year`required	integer	Model year between 1990 and next year. Must exist for the make/model in the catalog.
`view`required	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:

Header	Example	Meaning
`X-Credits-Charged`	1	Credits debited for this response — always 1 for a delivered image.
`X-Credits-Remaining`	4870	Balance after the debit. Plan top-ups before it reaches 0.
`X-Image-Source`	cache \| generated	Whether the render existed already. Same price either way.
`X-Image-Width`	1024	Delivered width in pixels.
`X-Image-Height`	1024	Delivered height in pixels.
`ETag`	"9f2a…c41d"	Stable per image variant. Send If-None-Match to receive a free 304.
`Cache-Control`	private, max-age=86400	Keyed responses may be kept by the caller for a day, never by shared caches.
`X-Request-Id`	req_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

First render and refunds

When a make/model/year/color/view combination has never been requested, the API renders it synchronously (about ten seconds) and caches it in a private origin. Concurrent requests for the same variant wait for the one render instead of paying twice. If rendering fails the request returns 502 and the credit is refunded.

Set a generous client timeout

Give the first request at least 30 seconds. Everything after that is a cache hit.

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.