Images

Parameters are read the way people write them: names in any case (Width, COLOR), view aliases such as left and front-right, grey and every CSS color name, whole numbers written 2024.0, and these other names:

• make: brand
• vehicle: vehicle_id
• view: angle, camera, perspective, orientation
• color: colour, paint, paint_color, hex, colors
• w: width
• h: height
• background: bg, background_color

Each spelling is the same image as the canonical one, cached once.

Only tracking tags and cache busters are ignored: every utm_* and every _* name, and gclid, gclsrc, gbraid, wbraid, gad_source, gad_campaignid, dclid, fbclid, msclkid, yclid, ttclid, twclid, li_fat_id, igshid, mc_cid, mc_eid, mkt_tok, srsltid, ref, ref_src, v, ver, t, ts, timestamp, cb, cachebuster, cache_buster, cachebust, nocache, bust, rand, random, nonce, dpl. They change the URL, never the image, and X-Ignored-Parameters names them. Any other parameter the endpoint does not read is a 400 that names it in parameter and lists every name the endpoint reads in allowed, and nothing is charged: an image served without it would be another image than the one asked for.

A size above 1024 is clamped and X-Clamped-Parameters gives the values served. A known parameter sent twice, or under two names (w and width, view and angle), is a 400, because one value would be lost. JSON bodies (signed URLs, 3D, the MCP tools) take the documented names and their spellings (width, colour, vehicle_id) but not the other words, and refuse an unknown field: a body is written by its sender alone, to a schema.

For a layout that is not square, ask for the box you have and trim to the car; for a page, let the browser pick the encoding; for a paint the presets do not have, write the hex bare; and when you already hold a vehicle id, send that instead of the three name parameters:

Eight fixed camera positions, described by where the camera stands around the vehicle: 0° is straight ahead of the nose, 90° level with the car's left side, 180° behind it and 270° level with its right side. The set is symmetric: front-3-4, side and rear-3-4 show the left side with the nose pointing left, and each has a -right twin that shows the right side with the nose pointing right. The framing is identical for every vehicle in the catalog, which is what makes listings and comparison grids line up.

Aliases are read in any case and with any separators (Front Left, front_left); left and right name the side of the car the camera sees, where the nose also points, so view=left is side and view=front-right is front-3-4-right. Every alias redirects to, and is cached as, the view it names.

Source renders are square 1024×1024 PNGs. Ask for a named preset with size=, or exact pixels with w= and h=: one dimension scales the square (w=600 is 600×600), both deliver exactly w×h, and fit decides how the car is placed in that box. Nothing is ever upscaled: 1024 px is the largest output, and a trimmed car is at most as large as it is in the source.

A size above 1024 is clamped rather than refused, and X-Clamped-Parameters gives the values served: a contain or cover box shrinks whole and keeps its shape (w=1920&h=1080 is delivered as 1024×576); one dimension, or an inside box, is capped on its own.

With both w and h the square source has to be placed in a box of another shape, and fit= chooses how (default contain); with one dimension every fit yields the same image. For w=600&h=400:

The square source leaves empty canvas above and below a car, so a box that is not square shows either padding or a crop. trim=1 crops to the car's own bounds (its alpha channel) before sizing, so the car itself fills the box — the setting to reach for in listing cards, table rows and hero sections — and padding= keeps a margin around it, 0–50 percent of the car's longer side (only with trim).

• With a box and contain or cover the canvas is still exactly w×h: it is the car, not the square, that gets fitted.
• With one dimension or fit=inside the output follows the car's aspect ratio (w=600&trim=1 is roughly 600×270 for a side view), and X-Image-Width and X-Image-Height report the exact size.

framing= names a composition instead of spelling one out. It is a preset, not another transform: the API rewrites it into the trim and padding it stands for before anything else reads the request, so framing=tight is the same image, canonical URL, cache entry, ETag and 1 credit as trim=1&padding=0, and responses echo trim and padding, never framing.

• Vehicle catalog grid: balanced, so every card has the same even margin whatever the car's shape.
• Dealership listing hero: balanced with a background that matches the page.
• Search-result thumbnails: tight at a small size, so the car uses every pixel of the slot.
• Multi-angle gallery or 360 spinner: consistent (or no framing at all). Since the coherent-views policy the eight views of one vehicle share one apparent camera scale; trimming each view to its own bounds would zoom the side profile and the front by different amounts.
• 3D preview poster: consistent, so the still matches the camera the model opens with.
• Two vehicles side by side: tight makes each car as large as its box allows; consistent keeps each vehicle's own camera scale. Neither shows how big the cars are relative to each other in the real world: each vehicle is framed on its own.

Sending framing with trim or padding (even framing=consistent&trim=0) is a free 400 that names both, and an unknown value is a free 400 that lists the three. Values are read in any case. Make logos do not take it.

A cut-out car can look pasted onto a page. shadow=1 grounds it: a soft, neutral shadow under the car, an ambient one along the line its tyres stand on and a darker contact shadow right under them. It is drawn at delivery from the render's own transparent cut-out, so it is the same car, not a new render, and it costs the same 1 credit.

• On a transparent PNG or WebP the shadow is semi-transparent, so it darkens whatever the image sits on; with a background or as JPG it is flattened into a soft grey.
• It is never drawn above the car and stays inside the frame; with trim=1 the crop keeps it, so a trimmed car is a little taller with a shadow than without.
• Off by default: an image without shadow is byte for byte what it was, with the same ETag. Make logos do not take it.

color= takes one of 15 preset names (grey is gray), any other CSS color name, or any paint as hex; the default is silver. Every color is a recolor of one neutral render of the vehicle, not a new generation, so a custom paint costs the same 1 credit as a preset and is cached the same way.

How hex is written

• In a URL, bare: color=1a2b3c is the canonical spelling, because an unescaped # starts the fragment (color=%231a2b3c works too); in JSON (signed URL items, 3D requests, MCP tools), "#1a2b3c" or "1a2b3c". Three-digit shorthand expands (1ab is 11aabb) and case does not matter.
• Responses echo hex as "color": "#1a2b3c" and presets by name. A hex that equals a preset's swatch exactly is that preset: color=b3151b is red, one cached image either way.
• A CSS color name (navy, Light Grey) is read as its CSS hex, in any case and with any separators — color=navy is the image color=000080 and is echoed that way — while the presets keep their own paint swatches, so red is #b3151b, not CSS #ff0000.

The resolve endpoint and the MCP tools' lookup, which pick a vehicle and a paint from a sentence, map free-text phrases ("midnight", "gunmetal") onto the nearest preset and keep a hex as is; the color parameter itself reads a CSS name exactly.

Renders are transparent; background= flattens one onto a solid color (a CSS name, or a bare hex such as background=f4f4f4, echoed as #f4f4f4), PNG and WebP included. JPG has no alpha channel: it defaults to #ffffff, and background=transparent with format=jpg is a 400.

format= accepts png, webp, jpg, auto: PNG (the default) and WebP keep the transparent background, JPG is composited onto it, and WebP is typically 3–5× smaller than PNG at the same size. format=auto lets each client choose (WebP when its Accept header lists image/webp, PNG otherwise, with Vary: Accept), so a signed URL minted with it negotiates on every load: the right choice for an <img> tag.

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

Send Accept: application/json (or response=url) 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.

The echoed vehicle opens with vehicle_id, the stable id of the catalog vehicle that was rendered (however you spelled it), then the delivery options you set: width, height, fit (only with a box), background, trim, padding and shadow. A hex paint is echoed as "color": "#1a2b3c". width and height are null when only the render can tell — a trimmed car without an exact box.

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

When a make/model/year/color/view combination has never been requested, the API renders it synchronously (about 20 seconds) and saves it in a private origin. Concurrent requests share one generation; each delivered image still costs one credit. If rendering fails the request returns 502 and the credit is refunded.

GET /images/car.png?…&mode=cached takes the same parameters, vehicle= included, needs no key and costs nothing. It never renders: it answers 200 with an image that already exists, or a fast 404 with code: "not_cached". Use it to show a picture at once when there is one, and to render the rest in the background.

1. Decode the VIN (free) or look the vehicle up, and keep its vehicle id.
2. Put the mode=cached URL in an <img>, or ask client.isImageReady() from the SDK.
3. On a 404, request the image with your key or POST /api/v1/image-urls (1 credit) without blocking the page, then swap it in.

Coverage is partial and changes as images are rendered, so treat a 404 as "not yet". A paint color can be answered from a neutral base of the view.

• 400 — a parameter is missing or invalid; the detail says which (a parameter sent twice or under two spellings, vehicle together with make, model or year, a color that is neither a preset, a CSS color name nor a hex, padding without trim, background=transparent with format=jpg). An unknown parameter is an error. Tracking tags and cache busters are ignored and listed in X-Ignored-Parameters.
• 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, or no vehicle has that id. Do not retry the same input. For catalog imports, use the years and vehicle ids returned by vehicle search instead of combining every model with every year. Review the response's suggestions or check the catalog's spelling and years before continuing.
• 429 — rate limited; wait Retry-After seconds.
• 502 — the render failed; refunded.

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