Průvodce implementací vycházející ze zdokumentovaného chování API; nejmenuje žádného zákazníka. Publikováno .
Problém: nabídka je přesná, obrázek ne
Nabídka leasingu je konkrétní: jeden modelový rok, výbava, pro kterou je splátka spočítána, lak z aktuální palety výrobce a měsíční částka platná do určitého data. Obrázek vedle ní často konkrétní není: loňská tisková fotografie, barva, ve které se vůz už nenabízí, jiná karoserie. Když je splátka přesná a obrázek jen přibližný, zákazník zpochybní právě obrázek.
Stejná nabídka pak putuje dál: na stránku modelu, do PDF nabídky, do e-mailu a do konfigurátoru, kde si zákazník vůz otáčí. Všude je potřeba stejné vozidlo ve stejné barvě.
Jak integrace vypadá
- Jedna nabídka na modelový rok, s klíčem v podobě katalogového id vozidla daného roku.
- Lak výrobce jako hex kód na každém obrázku nabídky.
- Stejný obrázek v PDF nabídky i v e-mailu díky podepsaným URL, takže žádný dokument ani vykreslovací nástroj nikdy nedrží klíč.
- 3D model pro každý lak pro konfigurátor, publikovaný jako dvouřádkový kód pro vložení.
Krok 1: přiřaďte každé nabídce id vozidla pro její modelový rok
GET /api/v1/vehicles?make=&model= je zdarma a veřejné a vypíše všechny ročníky modelu, každý s jeho stálým ID vozidla. K nabídce uložte ID modelového roku, kterého se nabídka týká.
curl -s "https://carimage.dev/api/v1/vehicles?make=honda&model=cr-v"{
"data": {
"make": {
"id": 474,
"name": "HONDA",
"slug": "honda"
},
"model": {
"name": "CR-V",
"slug": "cr-v",
"vehicle_type": "Passenger Car"
},
"vehicles": [
"…",
{
"year": 2025,
"id": "veh_exjyt8r21gmhe"
},
{
"year": 2026,
"id": "veh_b6kgpb03d73r9"
},
{
"year": 2027,
"id": "veh_8nr7res56a6jq"
}
]
}
}Když se spustí nabídky na rok 2027, dostanou ID ročníku 2027 a nabídky na rok 2026 si ponechají svá: ID se nikdy nemění, takže stránka nebo kalkulace na něm postavená funguje i po změně modelového roku. Katalog je klíčovaný značkou, modelem a rokem, takže výbava, pro kterou je splátka spočítána (EX-L, Sport Touring), je text u nabídky, nikdy něco, co tvrdí obrázek.
Krok 2: barva výrobce podle hex kódu
Přednastavené barvy (15) pokrývají běžné odstíny; nabídka ale potřebuje lak, ve kterém se auto skutečně nabízí. Vezměte hex ze vzorníku barev výrobce a pošlete ho bez znaku v URL (color=1f3a5f) nebo s # v JSON ("color": "#1f3a5f"). Hex se počítá stejně jako předvolba, jako jeden obrázek vozidla, protože každý lak je přebarvením jednoho připraveného pohledu, a hex shodný se vzorkem předvolby je touto předvolbou, uloženou v mezipaměti jednou.
# the 2026 offer's hero: its model year, in the paint it is offered in, cropped to a 16:9 slot
curl --fail-with-body -H "Authorization: Bearer $CAR_IMAGE_API_KEY" \
"https://carimage.dev/api/v1/images/car?vehicle=veh_b6kgpb03d73r9&view=front-3-4&color=1f3a5f&w=1024&h=576&fit=contain&trim=1&padding=4&format=webp" \
-o cr-v-2026-offer.webpKrok 3: PDF nabídky a e-mail s nabídkou přes podepsané URL
PDF s nabídkou je obvykle HTML vykreslené PDF službou nebo headless prohlížečem. Do šablony vložte podepsanou URL z POST /api/v1/image-urls, nikdy klíč: renderer obrázek načte jednou a vloží ho, takže výchozí doba platnosti 1 hodina bohatě stačí, a format: "jpg" ho zploští na bílé pozadí, což se k dokumentu hodí. URL se při vygenerování započítá jako obrázek vozidla daného měsíce.
E-mail s nabídkou se otevře, kdykoli se k němu zákazník dostane. Vygenerujte jeho obrázek s renew: true a ttl_seconds na maximu 7 dní a renew_days nastavte na počet dní zbývajících do konce nabídky: obnovení započítá obrázek jednou v měsíci, do kterého spadne, a nic navíc, pokud už byl v daném měsíci započítán; klidné týdny se nezapočítávají, a když nabídka skončí, URL se přestane obnovovat a vyprší. V placeném tarifu licence pokrývá render uvnitř výstupu, který váš produkt vytváří pro zákazníky, včetně nabídky.
import { CarImageClient, type ImageParams } from "@meterapp/car-image-sdk";
const client = new CarImageClient({ apiKey: process.env.CAR_IMAGE_API_KEY });
// The offer's picture: its model year, in the paint it is offered in.
const offerImage: ImageParams = {
vehicle: offer.vehicleId, view: "front-3-4", color: offer.paintHex, // "#1f3a5f"
width: 1024, height: 576, fit: "contain", trim: true, padding: 4,
};
// The quote PDF: rendered from HTML, the picture loaded once and embedded, on white.
const { data: [forPdf] } = await client.createImageUrls({ ...offerImage, format: "jpg" });
const pdf = await renderQuotePdf({ ...quote, vehicleImageUrl: forPdf.url });
// The offer email: loads for as long as the offer runs, then stops renewing.
const { data: [forEmail] } = await client.createImageUrls(
{ ...offerImage, width: 600, height: 338, format: "auto" },
{
ttlSeconds: 604800,
renew: true,
renewDays: Math.min(Math.max(daysUntil(offer.endsOn), 1), 365),
idempotencyKey: `offer:${offer.id}:email`,
}
);Krok 4: 3D model pro konfigurátor
POST /api/v1/3d s id vozidla z nabídky, jeho lakem a publish: true vytvoří texturovaný model (GLB, USDZ, FBX a verzi pro prohlížeč) a přidělí mu URL bez klíče s dvouřádkovým kódem pro vložení. Stojí to 100 kreditů za vozidlo a barvu z kreditů, které váš tarif zahrnuje, účtováno jednou; opětovná objednávka stejného vozidla ve stejném laku z vašeho účtu je zdarma. První model vozidla trvá 10–20 minutes a každý další lak znovu využije jeho síť (mesh) a trvá 1–2 minutes.
curl --fail-with-body -X POST https://carimage.dev/api/v1/3d \
-H "Authorization: Bearer $CAR_IMAGE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: configurator-cr-v-2026-1f3a5f" \
-d '{"vehicle": "veh_b6kgpb03d73r9", "color": "#1f3a5f", "publish": true}'{
"data": {
"id": "5b0f3c2e-8a41-4d7e-9c10-2f6e1a3b4d58",
"object": "3d_model",
"status": "queued",
"progress": 0,
"vehicle": {
"id": "veh_b6kgpb03d73r9",
"make": "honda",
"model": "cr-v",
"year": 2026
},
"color": "#1f3a5f",
"files": null,
"public": {
"id": "m3d_…",
"url": "https://carimage.dev/api/v1/3d/public/m3d_…",
"files": null,
"embed": {
"script": "https://carimage.dev/embed/3d.js",
"html": "<script src=\"https://carimage.dev/embed/3d.js\" async></script>\n<car-3d model=\"m3d_…\"></car-3d>"
}
}
},
"billing": {
"charged_on": "creation",
"credits_charged": 100,
"already_owned": false
}
}Dotazujte se na GET /api/v1/3d/{id} (stačí každých 10–15 sekund), nebo předejte webhook_url s webhook_secret a jakmile bude model hotový, obdržíte jeden podepsaný POST. data.public.embed.html obsahuje skript a element <car-3d>: vložte jej na stránku nabídky. Element okamžitě zobrazí náhledový obrázek a prohlížeč načte, až se model poprvé posune do zobrazení; view, spin, backdrop, ar a alt nastavují výchozí úhel, otočný stůl, pozadí, tlačítko AR na telefonech (Quick Look přes USDZ na iOS) a alternativní text. Publikování i každé načtení jsou zdarma.
<script src="https://carimage.dev/embed/3d.js" async></script>
<select id="paint" aria-label="Paint">
<option value="1f3a5f">Blue</option>
<option value="white">White</option>
</select>
<!-- One published model per paint. Only the visible one is loaded: the script
fetches a viewer the first time a model scrolls into view. -->
<car-3d data-paint="1f3a5f" model="m3d_…" view="front-3-4" spin backdrop="studio" ar
alt="2026 Honda CR-V in the offer's blue"></car-3d>
<car-3d data-paint="white" model="m3d_…" view="front-3-4" spin backdrop="studio" ar
alt="2026 Honda CR-V in white" hidden></car-3d>
<script>
document.querySelector("#paint").addEventListener("change", (event) => {
for (const model of document.querySelectorAll("car-3d[data-paint]")) {
model.hidden = model.dataset.paint !== event.target.value;
}
});
</script>Konfigurátor s 4 barvami laku znamená 4 modelů, jednorázově za 400 kreditů. Studia pro polepy a tónování skel, která API používají, objednávají 3D modely stejným způsobem; jejich příběh popisuje soubory a formáty a dokumentace k 3D pokrývá webhooky, stahování a zrušení publikování.
CLI, SDK a MCP
- CLI:
npx @meterapp/car-image 3d create --vehicle veh_b6kgpb03d73r9 --color "#1f3a5f" --publish --waitobjedná lak, počká na něj a vypíše kód pro vložení. - SDK:
client.vehicles({ make, model }),client.createImageUrls(…),client.create3dModel({ vehicle }, { color, publish: true })aclient.wait3dModel(id). - MCP: s
?toolset=allumožňujícreate_3d_model,get_3d_modelapublish_3d_modelasistentovi objednat a zveřejnit lak pro prodejce. Nastavení najdete na stránce MCP.
Často kladené otázky
- Zobrazuje obrázek tu výbavu, pro kterou je spočítána splátka?
- Ne. Katalog je založen na značce, modelu a roku, takže každá výbava daného modelového roku se vykreslí jako stejné vozidlo. Výbavu uveďte v textu nabídky vedle obrázku a obrázek nikdy nepopisujte jako tuto výbavu ani jako vůz skladem.
- Stojí lak výrobce víc než předvolba?
- Ne. Každý lak je přebarvením jednoho připraveného pohledu, takže hex se počítá jako jeden obrázek vozidla stejně jako kterákoli z 15 předvoleb, a hex shodný se vzorkem předvolby je přímo touto předvolbou. Hex se použije jako přesná hodnota sRGB ve studiovém osvětlení, proto před spuštěním nabídky porovnejte render se vzorkem barvy.
- Kolik stojí konfigurátor s počtem laků 4?
- 400 kreditů, jednorázově: 100 kreditů za každý lak vozidla. Opětovná objednávka vozidla a laku, které už váš účet má, je zdarma (billing.already_owned je true), a publikování, dotazování na stav, stahování i každé načtení publikovaného modelu jsou také zdarma.
- Jak dlouho trvá vytvoření 3D modelu a co když selže?
- První model vozidla trvá 10–20 minutes; každá další barva laku stejného vozidla znovu použije jeho síť a trvá 1–2 minutes. Za model, který selže, vrátíme celou částku, a když generování 3D dosáhne denní kapacity, požadavek se odmítne s časem pro opakování dřív, než se cokoli naúčtuje.
- Může si PDF kalkulace ponechat obrázek i po skončení nabídky?
- Ano. U placeného tarifu licence pokrývá render ve výstupech, které váš produkt vytváří pro zákazníky, včetně nabídky nebo brožury, a to po dobu, kdy je tarif aktivní; do 30 dnů po jeho skončení se uložené kopie mažou. Obrázky, které potřebujete v uložených nabídkách natrvalo, si můžete jednorázově koupit jako Image Pack.