Marketplaces & catalogs

Map your listings to vehicle ids once, render by id from your server, refresh with ETags.

GET/api/v1/images/car

images:read1 credit

Map names to ids once

A listing needs a picture before the seller uploads one, and your catalog spells its vehicles its own way. Look each one up once and store the veh_… vehicle id beside the listing: ids never change, so every render from then on is an id, not three names to get right.

GET /api/v1/vehicles lists years, makes and models; POST /api/v1/images/resolve reads one vehicle from free text. Both are free.
POST /api/v1/vehicles/check reads a whole list, 2,000 entries a call, as your data spells it, and answers what a render of each entry would do. Free too.

Render by id from your server and store the file

The image is one GET from your backend. Ask for the box your listing card shows (w, h), trim=1 so the car fills it and format=webp for the smallest file; a cold render and a saved one cost the same single credit. Store the file with the listing and serve your copy: your pages never wait on us, and each vehicle is one request.

bash

# render by id; keep the file and the headers
curl --fail-with-body \
  -H "Authorization: Bearer $CAR_IMAGE_API_KEY" \
  "https://carimage.dev/api/v1/images/car?vehicle=veh_errc87t1jgata&view=front-3-4&w=800&h=600&trim=1&format=webp" \
  --dump-header camry-2025.headers --output camry-2025.webp
# camry-2025.headers: etag: "9f2a…c41d"  x-credits-remaining: 24999

# refresh: send the ETag back; an unchanged image is a free 304
curl -sI \
  -H "Authorization: Bearer $CAR_IMAGE_API_KEY" \
  -H 'If-None-Match: "9f2a…c41d"' \
  "https://carimage.dev/api/v1/images/car?vehicle=veh_errc87t1jgata&view=front-3-4&w=800&h=600&trim=1&format=webp"
# HTTP/2 304

Refresh with the ETag

Keep the ETag with the file. A request that sends it back as If-None-Match answers 304 with no body and no charge while the render is unchanged, so a nightly pass over the whole catalog costs nothing until an image actually changes (ETags: free repeats). Storing copies to serve your product is covered by the commercial license while a paid plan is active (your license).

Render the catalog, not the grid

Use the years and ids the catalog returns, never every model times every year: a model year we do not carry is a 404 in every view and color. Pace batches under the per-key limit (120 requests a minute) and your plan's monthly cap on distinct vehicles (plans); a request past either is refused, and Errors says how to tell the two apart.

The long version, with pacing and the signed-URL variant: the marketplace story.