Může karta ukázat přesně to auto, které zákazník dostane?

Ne, a ani by se o to neměl pokoušet. Třída se pronajímá jako „nebo podobný“ a render zobrazuje značku, model a rok z katalogu, ne vůz na vašem parkovišti. Zobrazte jeden reprezentativní model s „nebo podobný“ v popisku. Jakmile je u přepážky přidělen konkrétní vůz, jeho VIN se zdarma dekóduje na odpovídající vozidlo z katalogu, pokud chcete místo toho zobrazit tento model.

Proč nejsou auta v mřížce ve správném měřítku?

Protože trim ořízne každý render na samotný vůz a fit=contain jím vyplní kartu, takže kompaktní vůz i velké SUV vyplní své karty stejně. Právě díky tomu zůstává mřížka úhledná. Velikost uveďte slovy: názvem třídy, počtem míst a zavazadel.

Kolik stojí mřížka tříd vozů?

Vozový park s počtem tříd 4, každá s kartou a hlavním obrázkem, představuje 8 obrázků vozidel měsíčně, každý doručovaný tak často, jak je třeba, v libovolné velikosti. Ukládejte soubory na svém CDN, dokud je placený tarif aktivní, a započítají se jen v měsíci, kdy je stáhnete, s bezplatným ověřováním přes ETag. Pokud místo toho poskytujete obnovované podepsané URL, tytéž obrázky se započítají jednou v každém měsíci, ve kterém se stránky otevřou.

Co když model dané třídy v katalogu není?

Vozidlo, které v katalogu není, vrátí 404 s návrhy: nejbližší vozidla z katalogu, každé s jeho id. Použijte jedno z nich, nebo o vozidlo požádejte na veřejné nástěnce požadavků. Katalog je open source.

Obrázky aut pro stránky vozového parku autopůjčoven

Průvodce implementací vycházející ze zdokumentovaného chování API; nejmenuje žádného zákazníka. Publikováno 30. září 2026.

Problém: pronajímáte třídu, ne auto

Zákazník autopůjčovny si rezervuje třídu, kompaktní vůz, střední SUV, minivan, a odjede tím vozem z dané třídy, který je zrovna na parkovišti. Rezervační stránka přesto potřebuje obrázek pro každou třídu a zvykem je jeden ilustrační model se slovy „nebo podobný“.

Takové obrázky obvykle pocházejí odkudkoli, kde se je podařilo najít: tu tisková fotka, tam fotka od dealera, různé úhly, různá pozadí, vozy, které vyplňují své karty pokaždé jinak. Mřížka sestavená tímto způsobem působí slepeně. Stránka s vozovým parkem potřebuje pravý opak: každou třídu zobrazenou stejně, aby se od karty ke kartě měnil jen samotný vůz.

Jak integrace vypadá

Jeden reprezentativní model na třídu, uložený jako ID vozidla z katalogu, s „nebo podobný“ v popisku a nikdy v obrázku.
Jeden tvar požadavku pro všechny karty: stejný pohled, rámec, přizpůsobení, ořez, odsazení, barva, pozadí a formát.
Nejvýše dva obrázky na třídu: karta v mřížce a hlavní obrázek na stránce třídy.
V mezipaměti, protože mřížka je pro každého návštěvníka stejná: soubory na vašem CDN, nebo podepsané URL vygenerované jednou a znovu používané.

Krok 1: vyberte reprezentativní model pro každou třídu, podle id

Zvolte model, pod kterým se jednotlivé třídy prodávají, a vyhledejte jeho aktuální modelový rok. GET /api/v1/vehicles?make=&model= je zdarma a veřejný a vypíše všechny roky jednoho modelu, každý se stabilním ID vozidla, které si uložíte; POST /api/v1/images/resolve udělá totéž z fráze jako „2026 toyota rav4“.

Id jednoho modelového roku

# one model's years, each with its vehicle id (free, public)
curl -s "https://carimage.dev/api/v1/vehicles?make=toyota&model=rav4" | jq -c '.data.vehicles[] | select(.year == 2026)'
# {"year":2026,"id":"veh_e5w75c93f6cvk"}

fleet.ts

// One representative model per class: its current model year, by catalog id.
// "or similar" lives in the label; the picture never promises the car on the lot.
export const CLASS_IMAGES = {
  compact:        { vehicle: "veh_fy7r2yvwt4p1v", label: "Toyota Corolla or similar" },    // 2026 Toyota Corolla
  "midsize-suv":  { vehicle: "veh_e5w75c93f6cvk", label: "Toyota RAV4 or similar" },       // 2026 Toyota RAV4
  "fullsize-suv": { vehicle: "veh_9mzh9ejqjye43", label: "Chevrolet Tahoe or similar" },   // 2026 Chevrolet Tahoe
  minivan:        { vehicle: "veh_9jck7rrybf35p", label: "Chrysler Pacifica or similar" }, // 2026 Chrysler Pacifica
};

ID se nikdy nemění, takže tato mapa je jediné místo, kterého se změna vozového parku dotkne: když třída střední velikosti přejde na jiný model nebo na další modelový rok, nahradíte jedno ID a každá karta, úvodní sekce i e-mail, které z mapy čtou, se změní s ní.

Krok 2: jeden tvar požadavku pro každou třídu

Všech 9 pohledů kamery má u každého vozidla v katalogu stejnou kompozici, a právě proto se mřížka zarovná. Zbytek karty tvoří několik parametrů, které stanovíte jednou:

view=side pro karty: každé auto směřuje stejným směrem na stejné základní linii. Každý úhel levé strany má dvojče -right (side-right), takže karty mohou směřovat dovnitř rozvržení. Stránka třídy používá front-3-4, hlavní úhel.
w=640&h=320&fit=contain: přesně 640×320 pro každou třídu, celé auto viditelné. Hlavičky odpovědi X-Image-Width a X-Image-Height potvrdí rozměry plátna.
trim=1&padding=6: před umístěním ořízne obrázek na auto s okrajem 6 % jeho delší strany, takže Corolla i Tahoe vyplní své karty stejně, místo aby plavaly ve čtvercovém zdrojovém rámu.
background=f4f4f4 sloučí kartu s vlastní šedou barvou mřížky. Pokud parametr vynecháte, zůstane průhledné pozadí a prosvitne barva karty.
format=webp pro uložené soubory; format=auto u podepsaných URL, které každému prohlížeči doručí WebP nebo PNG.

Karta a hlavní obrázek pro jednu třídu

# the class card: the same box, view, crop, paint and backdrop for every class
curl --fail-with-body -H "Authorization: Bearer $CAR_IMAGE_API_KEY" \
  "https://carimage.dev/api/v1/images/car?vehicle=veh_e5w75c93f6cvk&view=side&color=white&w=640&h=320&fit=contain&trim=1&padding=6&background=f4f4f4&format=webp" \
  -o midsize-suv-card.webp

# the class page's hero: the three-quarter view, the full width the API delivers
curl --fail-with-body -H "Authorization: Bearer $CAR_IMAGE_API_KEY" \
  "https://carimage.dev/api/v1/images/car?vehicle=veh_e5w75c93f6cvk&view=front-3-4&color=white&w=1024&format=webp" \
  -o midsize-suv-hero.webp

Krok 3: jedna pojmenovaná barva pro celou mřížku

Předvolby (15) jsou pojmenované laky: white, black, gray, silver, blue, red, green, brown, beige, tan, orange, yellow, gold, burgundy, purple. Výchozí je silver a grey se čte jako gray. Pro každou třídu zvolte jednu, aby karty působily jako sada; výše je zobrazena white. Každá předvolba má vlastní vzorek laku, nikoli stejnojmennou barvu CSS (red je #b3151b), a každý lak, včetně hex kódu, je přebarvením jednoho připraveného pohledu, takže každý lak představuje jeden obrázek vozidla.

Obrázek ukazuje model, slova dávají příslib

Render zobrazuje značku, model a modelový rok z katalogu, ne auto na vašem parkovišti, a zákazník dostane takovou barvu a výbavu, jakou zrovna máte k dispozici. Ponechte „nebo podobné“, počet sedadel a zavazadel v textu karty vedle obrázku.

Krok 4: uložte soubory nebo URL do mezipaměti

Mřížka tříd je pro každého návštěvníka stejná, takže by na jednu návštěvu měla stát téměř nic. Vedou k tomu dvě cesty:

Ukládejte soubory. Každou kartu a hlavní obrázek si jednou stáhněte pomocí GET /api/v1/images/car a poskytujte je ze své CDN jako jakýkoli jiný soubor; placený tarif po dobu, kdy je aktivní, umožňuje mít kopie na vlastních serverech pro provoz vašeho produktu (do 30 dnů po jeho skončení je smažte, nebo si kupte Image Pack a sadu si ponechte natrvalo). Uchovávejte ETag každého souboru: noční kontrola s If-None-Match vrátí 304 a nic nestojí. Pro výše uvedenou flotilu to je 8 obrázků vozidel za měsíc, které lze znovu použít, kolikrát je potřeba.
Nebo si podepsané URL vystavte jednou a používejte je opakovaně. POST /api/v1/image-urls přijme až 50 obrázků na jedno volání a vrátí URL bez klíče s platností až 7 dnů. URL s neomezeným počtem použití lze po dobu platnosti veřejně cachovat, takže když všichni návštěvníci načítají stejnou URL, opakovaná načtení jdou zdarma z CDN. Přidejte renew: true a uložená URL bude fungovat i po skončení platnosti; obnovení započítá obrázek jednou v měsíci, kdy proběhne, a nic dalšího, pokud už byl v daném měsíci započítán, takže výše uvedená flotila spotřebuje měsíčně nejvýše 8 obrázků vozidel.

Omezte klíč, kterým URL generujete, na doménu vašeho rezervačního webu v dashboardu a URL zkopírovaná na jiný web vrátí 403.

URL mřížky, vygenerované jednou, pomocí TypeScript SDK

import { CarImageClient, type ImageParams } from "@meterapp/car-image-sdk";
import { CLASS_IMAGES } from "./fleet";

const client = new CarImageClient({ apiKey: process.env.CAR_IMAGE_API_KEY });

// Framed once, for every class.
const card = (vehicle: string): ImageParams => ({
  vehicle, view: "side", color: "white", width: 640, height: 320,
  fit: "contain", trim: true, padding: 6, background: "#f4f4f4", format: "auto",
});
const hero = (vehicle: string): ImageParams => ({ vehicle, view: "front-3-4", color: "white", width: 1024, format: "auto" });

// Every visitor sees the same grid: mint the URLs once and serve the stored ones.
// renew keeps each URL working past its 7-day lifetime, one credit per image
// for each further week in which it is loaded.
const classes = Object.entries(CLASS_IMAGES);
const { data } = await client.createImageUrls(
  classes.flatMap(([, entry]) => [card(entry.vehicle), hero(entry.vehicle)]),
  { ttlSeconds: 604800, renew: true, idempotencyKey: "class-grid-2026-10" }
);
await saveClassImages(
  classes.map(([key], index) => ({ key, card: data[2 * index].url, hero: data[2 * index + 1].url, renewsUntil: data[2 * index].renews_until }))
);

Krok 5: potvrzení rezervace

E-mail s potvrzením ukazuje rezervovanou třídu a e-maily se otevírají, kdykoli se k nim nájemce dostane. Vytvořte její obrázek jako obnovující se URL: ttl_seconds na maximální hodnotě 7 dní, renew: true a renew_days sahající až za datum vrácení. Týdny, kdy e-mail nikdo neotevře, nic nestojí, a po skončení pronájmu se URL přestane obnovovat. Idempotency-Key pro každou rezervaci zajistí, že opakované odeslání vrátí první URL místo vytvoření druhé, a uložení URL k rezervaci umožní její opětovné použití při každém dalším odeslání. Takto fungují i naše vlastní e-maily životního cyklu; mechanismus i HTML najdete v příběhu o e-mailech.

Obnovující se URL pro jedno potvrzení

// The booking confirmation: opened today, again at the counter, maybe never.
const { data: [classImage] } = await client.createImageUrls(card(booking.classVehicle), {
  ttlSeconds: 604800,
  renew: true,
  // A week past the return date, and no renewals after it (365 days at most).
  renewDays: Math.min(daysUntil(booking.returnDate) + 7, 365),
  // A retried send replays the first URL instead of minting a second one.
  idempotencyKey: `booking:${booking.id}:class`,
});
booking.classImageUrl = classImage.url; // later resends reuse it

CLI, SDK a MCP

CLI: npx @meterapp/car-image get --vehicle veh_… --view side --width 640 --height 320 --fit contain --trim --padding 6 --out card.webp zapíše kartu do souboru; car-image url --batch classes.json --renew vygeneruje dávku URL.
SDK: client.vehicles({ make, model }) pro ID, client.getImage(…) pro soubory, client.createImageUrls(…) pro URL.
MCP: resolve_vehicle a create_car_image_urls umožňují asistentovi připravit kartu kategorie z popisu „střední SUV, RAV4 nebo podobné“. Nastavení najdete na stránce MCP.

Často kladené otázky

Může karta ukázat přesně to auto, které zákazník dostane?: Ne, a ani by se o to neměl pokoušet. Třída se pronajímá jako „nebo podobný“ a render zobrazuje značku, model a rok z katalogu, ne vůz na vašem parkovišti. Zobrazte jeden reprezentativní model s „nebo podobný“ v popisku. Jakmile je u přepážky přidělen konkrétní vůz, jeho VIN se zdarma dekóduje na odpovídající vozidlo z katalogu, pokud chcete místo toho zobrazit tento model.
Proč nejsou auta v mřížce ve správném měřítku?: Protože trim ořízne každý render na samotný vůz a fit=contain jím vyplní kartu, takže kompaktní vůz i velké SUV vyplní své karty stejně. Právě díky tomu zůstává mřížka úhledná. Velikost uveďte slovy: názvem třídy, počtem míst a zavazadel.
Kolik stojí mřížka tříd vozů?: Vozový park s počtem tříd 4, každá s kartou a hlavním obrázkem, představuje 8 obrázků vozidel měsíčně, každý doručovaný tak často, jak je třeba, v libovolné velikosti. Ukládejte soubory na svém CDN, dokud je placený tarif aktivní, a započítají se jen v měsíci, kdy je stáhnete, s bezplatným ověřováním přes ETag. Pokud místo toho poskytujete obnovované podepsané URL, tytéž obrázky se započítají jednou v každém měsíci, ve kterém se stránky otevřou.
Jakou barvu laku má mřížka použít?: Pro všechny třídy jednu předvolbu, aby karty působily jako jedna sada. Předvoleb je 15: white, black, gray, silver, blue, red, green, brown, beige, tan, orange, yellow, gold, burgundy, purple, výchozí je silver; funguje i libovolný hex kód za stejnou cenu. Zákazník dostane barvu vozu, který je zrovna na parkovišti, což karta nikdy neslibovala.
Co když model dané třídy v katalogu není?: Vozidlo, které v katalogu není, vrátí 404 s návrhy: nejbližší vozidla z katalogu, každé s jeho id. Použijte jedno z nich, nebo o vozidlo požádejte na veřejné nástěnce požadavků. Katalog je open source.

Čtěte dál

Příběh zákazníka · Vývojářské nástrojeJak vkládat obrázky aut do e-mailů pomocí podepsaných URL, které nikdy nepřestanou fungovatNaše vlastní e-maily v průběhu zákaznického cyklu vkládají přesně ten první render každého zákazníka jako živou podepsanou URL, která se sama obnovuje po dobu jednoho roku. Ukážeme vám, jak to funguje a jak to napodobit.