Una guida pratica scritta a partire dal comportamento documentato dell'API; non nomina alcun cliente. Pubblicato il .
Il problema: l'offerta è esatta, l'immagine no
Un'offerta di leasing è precisa: un anno modello, l'allestimento su cui è calcolata la rata, un colore della gamma attuale del costruttore, un importo mensile valido fino a una certa data. L'immagine accanto spesso non lo è: la foto stampa dell'anno scorso, un colore non più disponibile per quell'auto, una carrozzeria diversa. Quando la rata è esatta e l'immagine è approssimativa, è l'immagine che il cliente mette in dubbio.
La stessa offerta poi viaggia: su una pagina modello, in un PDF di preventivo, in un’email e in un configuratore dove il cliente fa ruotare l’auto. Ognuno di questi richiede lo stesso veicolo nella stessa vernice.
Come si presenta l'integrazione
- Un'offerta per anno modello, identificata dall'id del veicolo a catalogo per quell'anno.
- La vernice del costruttore in esadecimale, su ogni immagine dell'offerta.
- La stessa immagine nel PDF del preventivo e nell'email, tramite URL firmati, così nessun documento o renderer contiene mai una chiave.
- Un modello 3D per ogni vernice per il configuratore, pubblicato come embed di due righe.
Passo 1: associare ogni offerta all'id veicolo del relativo anno modello
GET /api/v1/vehicles?make=&model= è gratuito e pubblico ed elenca ogni anno di un modello, ciascuno con il proprio ID veicolo stabile. Salvi l'ID dell'anno modello dell'offerta insieme all'offerta.
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"
}
]
}
}Quando le offerte 2027 vanno online prendono l'ID 2027, mentre le offerte 2026 mantengono il loro: un ID non cambia mai, quindi una pagina o un preventivo costruiti su di esso continuano a funzionare dopo il cambio di anno modello. Il catalogo si basa su marca, modello e anno, quindi l'allestimento su cui è calcolata la rata (un EX-L, uno Sport Touring) è testo nell'offerta, mai qualcosa che l'immagine rappresenta.
Passaggio 2: la vernice del costruttore, tramite hex
I 15 colori predefiniti coprono i colori più comuni; un'offerta richiede la vernice in cui l'auto è effettivamente proposta. Prenda l'esadecimale dal campione colore del produttore e lo invii senza prefisso in un URL (color=1f3a5f) o con il suo # in JSON ("color": "#1f3a5f"). Un esadecimale conta come un predefinito, un'immagine di veicolo, perché ogni vernice è una ricolorazione di un'unica vista preparata, e un esadecimale uguale al campione di un predefinito è quel predefinito, memorizzato in cache una sola volta.
# 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.webpPassaggio 3: il PDF del preventivo e l’email dell’offerta, tramite URL firmati
Un preventivo in PDF è di solito HTML renderizzato da un servizio PDF o da un browser headless. Inserisca nel template un URL firmato da POST /api/v1/image-urls, mai la chiave: il renderer carica l'immagine una volta e la incorpora, quindi la durata predefinita di 1 ora è più che sufficiente, e format: "jpg" la appiattisce su sfondo bianco, ideale per un documento. L'URL conteggia la sua immagine come immagine di veicolo del mese al momento della generazione.
L'email con l'offerta viene aperta quando il cliente ci arriva. Generi la sua immagine con renew: true e ttl_seconds al massimo di 7 giorni, e imposti renew_days sui giorni rimanenti dell'offerta: un rinnovo conta l'immagine una volta nel mese in cui avviene, e nient'altro se era già stata conteggiata quel mese; le settimane senza aperture non contano nulla, e quando l'offerta termina l'URL smette di rinnovarsi e scade. Con un piano a pagamento la licenza copre un render all'interno di ciò che il suo prodotto genera per i clienti, preventivi compresi.
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`,
}
);Passaggio 4: un modello 3D per il configuratore
POST /api/v1/3d con l’id del veicolo dell’offerta, la sua vernice e publish: true crea un modello con texture (GLB, USDZ, FBX e una versione per browser) e gli assegna URL senza chiave con un embed di due righe. Costa 100 crediti per veicolo e colore, prelevati dai crediti inclusi nel Suo piano e addebitati una sola volta; ordinare di nuovo lo stesso veicolo nella stessa vernice dal Suo account è gratuito. Il primo modello di un veicolo richiede 10–20 minutes, e ogni vernice successiva ne riutilizza la mesh e richiede 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
}
}Interroghi GET /api/v1/3d/{id} (ogni 10–15 secondi è più che sufficiente), oppure passi un webhook_url con un webhook_secret e riceva un'unica POST firmata quando il modello è pronto. data.public.embed.html contiene lo script e un elemento <car-3d>: lo incolli nella pagina dell'offerta. L'elemento mostra subito l'immagine di anteprima e carica il visualizzatore la prima volta che il modello entra nella visuale durante lo scorrimento; view, spin, backdrop, ar e alt impostano l'angolazione iniziale, la rotazione, lo sfondo, un pulsante AR sui telefoni (Quick Look tramite l'USDZ su iOS) e il testo alternativo. La pubblicazione e ogni caricamento sono gratuiti.
<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 configuratore con 4 colori di vernice equivale a 4 modelli, 400 crediti una sola volta. Le officine di wrapping e oscuramento vetri che usano l’API ordinano i modelli 3D allo stesso modo; la loro storia descrive i file e i formati, mentre la documentazione 3D tratta webhook, download e rimozione dalla pubblicazione.
CLI, SDK e MCP
- CLI:
npx @meterapp/car-image 3d create --vehicle veh_b6kgpb03d73r9 --color "#1f3a5f" --publish --waitordina un colore, ne attende il completamento e stampa il codice di incorporamento. - SDK:
client.vehicles({ make, model }),client.createImageUrls(…),client.create3dModel({ vehicle }, { color, publish: true })eclient.wait3dModel(id). - MCP: con
?toolset=all,create_3d_model,get_3d_modelepublish_3d_modelconsentono a un assistente di ordinare e pubblicare una vernice per un venditore. La configurazione è descritta nella pagina MCP.
Domande frequenti
- L’immagine mostra l’allestimento su cui è calcolata la rata?
- No. Il catalogo si basa su marca, modello e anno, quindi ogni allestimento di un anno modello viene renderizzato come lo stesso veicolo. Indichi l'allestimento nel testo dell'offerta, accanto all'immagine, e non descriva mai l'immagine come quell'allestimento o come un'auto disponibile in stock.
- Una vernice del costruttore costa più di un preset?
- No. Ogni vernice è una ricolorazione di un'unica vista preparata, quindi un esadecimale conta come un'immagine di veicolo, come uno qualsiasi dei 15 colori predefiniti, e un esadecimale uguale al campione di un predefinito è quel predefinito. L'esadecimale viene applicato come quel valore sRGB esatto con illuminazione da studio, quindi confronti il render con il campione colore prima che l'offerta vada online.
- Quanto costa un configuratore con 4 colori?
- 400 crediti, una sola volta: 100 crediti per ogni colore del veicolo. Ordinare di nuovo un veicolo e un colore che il suo account possiede già è gratuito (billing.already_owned è true), e anche pubblicazione, polling, download e ogni caricamento di un modello pubblicato sono gratuiti.
- Quanto tempo richiede un modello 3D e cosa succede se non va a buon fine?
- Il primo modello di un veicolo richiede 10–20 minutes; ogni ulteriore colore dello stesso veicolo riutilizza la sua mesh e richiede 1–2 minutes. Un modello non riuscito viene rimborsato per intero e, quando la generazione 3D ha raggiunto la capacità giornaliera, la richiesta viene rifiutata con un orario per riprovare, prima che venga addebitato qualsiasi importo.
- Un PDF di preventivo può mantenere l'immagine dopo la scadenza dell'offerta?
- Sì. Con un piano a pagamento la licenza copre un render all’interno di ciò che il suo prodotto genera per i clienti, inclusi un preventivo o una brochure, finché il piano è attivo; entro 30 giorni dalla sua scadenza, le copie archiviate vengono eliminate. Le immagini che le servono in modo permanente nei preventivi archiviati possono essere acquistate una sola volta come Image Pack.