Un ghid de implementare scris pe baza comportamentului documentat al API-ului; nu numește niciun client. Publicat pe .
Problema: oferta este exactă, imaginea nu
O ofertă de leasing este precisă: un singur an de model, versiunea de echipare pentru care este calculată rata, o culoare din paleta actuală a producătorului, o sumă lunară valabilă până la o anumită dată. Imaginea de lângă ea adesea nu este: fotografia de presă de anul trecut, o culoare în care mașina nu mai este oferită, o altă caroserie. Când rata este exactă și imaginea aproximativă, imaginea este partea pe care clientul o pune la îndoială.
Aceeași ofertă circulă apoi: pe o pagină de model, într-un PDF cu oferta, într-un e-mail și într-un configurator în care clientul rotește mașina. Fiecare dintre acestea are nevoie de același vehicul în aceeași culoare.
Cum arată integrarea
- O ofertă pentru fiecare an de model, identificată prin id-ul vehiculului din catalog pentru acel an.
- Culoarea de vopsea a producătorului în format hex, pe fiecare imagine a ofertei.
- Aceeași imagine în PDF-ul ofertei și în e-mail, prin URL-uri semnate, astfel încât niciun document sau motor de randare să nu dețină vreodată o cheie.
- Un model 3D pentru fiecare culoare pentru configurator, publicat printr-un cod de încorporare de două rânduri.
Pasul 1: asociați fiecare ofertă cu id-ul vehiculului pentru anul său de model
GET /api/v1/vehicles?make=&model= este gratuit și public și listează fiecare an al unui model, fiecare cu ID-ul său stabil de vehicul. Stocați ID-ul anului de model al ofertei împreună cu oferta.
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"
}
]
}
}Când ofertele pentru 2027 sunt publicate, ele primesc id-ul 2027, iar ofertele pentru 2026 îl păstrează pe al lor: un id nu se schimbă niciodată, astfel încât o pagină sau o cotație construită pe baza lui continuă să funcționeze după schimbarea anului modelului. Catalogul este indexat după marcă, model și an, așa că versiunea de echipare pentru care este calculată rata (un EX-L, un Sport Touring) este text în ofertă, niciodată ceva ce susține imaginea.
Pasul 2: culoarea producătorului, după codul hex
Cele 15 culori predefinite acoperă culorile uzuale; o ofertă are nevoie de vopseaua în care mașina este oferită efectiv. Luați codul hex din mostra de culoare a producătorului și trimiteți-l simplu într-un URL (color=1f3a5f) sau cu # în JSON ("color": "#1f3a5f"). Un hex contează la fel ca o culoare predefinită, o imagine de vehicul, pentru că fiecare vopsea este o recolorare a unei vederi pregătite, iar un hex identic cu mostra unei culori predefinite este chiar acea culoare, stocată în cache o singură dată.
# 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.webpPasul 3: PDF-ul cu oferta de preț și e-mailul cu oferta, prin URL-uri semnate
Un PDF cu oferta de preț este de obicei HTML randat de un serviciu PDF sau de un browser headless. Puneți în șablon un URL semnat obținut de la POST /api/v1/image-urls, niciodată cheia: motorul de randare încarcă imaginea o singură dată și o încorporează, așa că durata de valabilitate implicită de 1 oră este suficientă, iar format: "jpg" o aplatizează pe fundal alb, ceea ce se potrivește unui document. URL-ul își contorizează imaginea ca imagine de vehicul a lunii în momentul în care este generat.
E-mailul cu oferta este deschis oricând ajunge clientul la el. Generați imaginea acestuia cu renew: true și ttl_seconds la maximul de 7 zile și setați renew_days la numărul de zile rămase din ofertă: o reînnoire contorizează imaginea o singură dată în luna în care are loc și nimic în plus dacă a fost deja contorizată în acea lună, săptămânile fără activitate nu se contorizează, iar când oferta se încheie, URL-ul nu se mai reînnoiește și expiră. Pe un plan plătit, licența acoperă o randare inclusă în ceea ce generează produsul dumneavoastră pentru clienți, inclusiv o ofertă de preț.
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`,
}
);Pasul 4: un model 3D pentru configurator
POST /api/v1/3d cu id-ul vehiculului din ofertă, vopseaua acestuia și publish: true construiește un model texturat (GLB, USDZ, FBX și o versiune pentru browser) și îi oferă URL-uri fără cheie, cu un cod de încorporare de două rânduri. Costă 100 de credite per vehicul și culoare din creditele incluse în plan, debitate o singură dată; o nouă comandă pentru același vehicul în aceeași vopsea din contul dumneavoastră este gratuită. Primul model al unui vehicul durează 10–20 minutes, iar fiecare vopsea suplimentară reutilizează mesh-ul acestuia și durează 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
}
}Interogați GET /api/v1/3d/{id} (o dată la 10–15 secunde este suficient) sau transmiteți un webhook_url cu un webhook_secret și primiți un singur POST semnat când modelul este gata. data.public.embed.html conține scriptul și un element <car-3d>: lipiți-l în pagina ofertei. Elementul afișează imediat imaginea de previzualizare și încarcă vizualizatorul prima dată când modelul intră în câmpul vizual la derulare; view, spin, backdrop, ar și alt setează unghiul inițial, platforma rotativă, fundalul, un buton AR pe telefoane (Quick Look prin USDZ pe iOS) și textul alternativ. Publicarea și fiecare încărcare sunt gratuite.
<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>Un configurator în 4 culori înseamnă 4 modele, adică 400 de credite, plătite o singură dată. Atelierele de colantare și de folii auto care folosesc API-ul comandă modele 3D în același mod; povestea lor tratează fișierele și formatele, iar documentația 3D tratează webhook-urile, descărcările și anularea publicării.
CLI, SDK și MCP
- CLI:
npx @meterapp/car-image 3d create --vehicle veh_b6kgpb03d73r9 --color "#1f3a5f" --publish --waitcomandă o culoare, așteaptă finalizarea și afișează codul de încorporare. - SDK:
client.vehicles({ make, model }),client.createImageUrls(…),client.create3dModel({ vehicle }, { color, publish: true })șiclient.wait3dModel(id). - MCP: cu
?toolset=all,create_3d_model,get_3d_modelșipublish_3d_modelpermit unui asistent să comande și să publice o culoare pentru un agent de vânzări. Configurarea este descrisă pe pagina MCP.
Întrebări frecvente
- Imaginea arată versiunea de echipare pentru care este calculată rata?
- Nu. Catalogul se bazează pe marcă, model și an, deci toate versiunile de echipare ale unui an de model sunt randate ca același vehicul. Menționați versiunea în textul ofertei, lângă imagine, și nu descrieți niciodată imaginea ca fiind acea versiune sau o mașină din stoc.
- Costă o culoare de producător mai mult decât una predefinită?
- Nu. Fiecare vopsea este o recolorare a unei vederi pregătite, așa că un hex contează ca o imagine de vehicul, la fel ca oricare dintre cele 15 culori predefinite, iar un hex identic cu mostra unei culori predefinite este chiar acea culoare. Hexul se aplică exact ca valoarea sRGB respectivă, sub iluminare de studio, așa că comparați randarea cu mostra de culoare înainte ca oferta să fie publicată.
- Cât costă un configurator în 4 culori?
- 400 de credite, o singură dată: 100 de credite pentru fiecare culoare a vehiculului. Comandarea din nou a unui vehicul și a unei culori pe care contul dumneavoastră le deține deja este gratuită (billing.already_owned este true), iar publicarea, interogarea periodică (polling), descărcările și fiecare încărcare a unui model publicat sunt, de asemenea, gratuite.
- Cât durează generarea unui model 3D și ce se întâmplă dacă eșuează?
- Primul model al unui vehicul durează 10–20 minutes; fiecare culoare suplimentară a aceluiași vehicul îi reutilizează mesh-ul și durează 1–2 minutes. Un model care eșuează este rambursat integral, iar când generarea 3D și-a atins capacitatea zilnică, cererea este refuzată cu un timp de reîncercare, înainte de a se taxa ceva.
- Poate un PDF de cotație să păstreze imaginea după încheierea ofertei?
- Da. Pe un plan plătit, licența acoperă o randare inclusă în ceea ce produsul dumneavoastră generează pentru clienți, inclusiv o ofertă sau o broșură, cât timp planul este activ; în termen de 30 de zile de la încheierea acestuia, copiile stocate se șterg. Imaginile de care aveți nevoie definitiv în ofertele stocate pot fi cumpărate o singură dată, sub forma unui Image Pack.