Un guide d’intégration rédigé à partir du comportement documenté de l’API ; il ne cite aucun client. Publié le .
Le problème : l'offre est exacte, l'image ne l'est pas
Une offre de location longue durée est précise : une année-modèle, la finition sur laquelle la mensualité est calculée, une teinte de la palette actuelle du constructeur, un montant mensuel valable jusqu’à une date donnée. L’image à côté ne l’est souvent pas : la photo presse de l’an dernier, une couleur qui n’est plus proposée, une autre carrosserie. Quand la mensualité est exacte et l’image approximative, c’est l’image que le client remet en question.
La même offre circule ensuite : sur une page modèle, dans un devis PDF, dans un e-mail et dans un configurateur où le client fait pivoter la voiture. Chacun de ces supports a besoin du même véhicule dans la même teinte.
À quoi ressemble l’intégration
- Une offre par année-modèle, associée à l'identifiant de véhicule du catalogue pour cette année.
- La teinte du constructeur en hexadécimal, sur chaque image de l’offre.
- La même image dans le devis PDF et dans l’e-mail, grâce aux URL signées : aucun document ni moteur de rendu ne détient jamais de clé.
- Un modèle 3D par teinte pour le configurateur, publié sous forme d’intégration de deux lignes.
Étape 1 : associez chaque offre à l’identifiant de véhicule de son millésime
GET /api/v1/vehicles?make=&model= est gratuit et public, et liste toutes les années d’un modèle, chacune avec son identifiant de véhicule stable. Enregistrez avec l’offre l’identifiant du millésime concerné.
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"
}
]
}
}Quand les offres 2027 sont mises en ligne, elles prennent l’identifiant 2027, et les offres 2026 gardent le leur : un identifiant ne change jamais, donc une page ou un devis construit dessus continue de fonctionner après le changement de millésime. Le catalogue est indexé par marque, modèle et année : la finition sur laquelle la mensualité est calculée (une EX-L, une Sport Touring) est donc un texte de l’offre, jamais une information que l’image revendique.
Étape 2 : la peinture du constructeur, par code hex
Les 15 préréglages couvrent les couleurs courantes ; une offre exige la peinture dans laquelle la voiture est réellement proposée. Relevez le code hexadécimal sur le nuancier du constructeur et envoyez-le tel quel dans une URL (color=1f3a5f) ou avec son # en JSON ("color": "#1f3a5f"). Un code hexadécimal coûte le même prix qu’un préréglage, soit 1 crédit, car chaque peinture est une recoloration d’un même rendu neutre, et un code hexadécimal identique à la teinte d’un préréglage correspond à ce préréglage, mis en cache une seule fois.
# 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.webpÉtape 3 : le devis PDF et l’e-mail d’offre, via des URL signées
Un devis PDF est généralement du HTML rendu par un service PDF ou un navigateur headless. Placez dans le modèle une URL signée issue de POST /api/v1/image-urls, jamais la clé : le moteur de rendu charge l’image une seule fois et l’intègre, donc la durée de vie par défaut de 1 heure suffit largement, et format: "jpg" l’aplatit sur fond blanc, ce qui convient à un document. L’URL coûte 1 crédit lors de sa génération.
L'e-mail de l'offre est ouvert quand le client en a le temps. Générez son image avec renew: true et ttl_seconds au maximum de 7 jours, et réglez renew_days sur le nombre de jours restants de l'offre : chaque semaine supplémentaire où l'e-mail est ouvert coûte 1 crédit, les semaines sans ouverture ne coûtent rien, et à la fin de l'offre, l'URL cesse de se renouveler et expire. Avec un forfait payant, la licence couvre un rendu intégré à ce que votre produit génère pour vos clients, devis compris.
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`,
}
);Étape 4 : un modèle 3D pour le configurateur
POST /api/v1/3d, avec l’identifiant du véhicule de l’offre, sa peinture et publish: true, génère un modèle texturé (GLB, USDZ, FBX et une version pour navigateur) et lui attribue des URL sans clé, avec un code d’intégration de deux lignes. Cela coûte 100 crédits (1,00 $US) par véhicule et par couleur, facturé une seule fois ; commander à nouveau le même véhicule dans la même peinture depuis votre compte est gratuit. Le premier modèle d’un véhicule prend 10–20 minutes, et chaque peinture supplémentaire réutilise son maillage et prend 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
}
}Interrogez GET /api/v1/3d/{id} (toutes les 10 à 15 secondes, c'est largement suffisant), ou passez un webhook_url avec un webhook_secret et recevez un unique POST signé quand le modèle est prêt. data.public.embed.html contient le script et un élément <car-3d> : collez-le dans la page de l'offre. L'élément affiche immédiatement l'image d'aperçu et charge la visionneuse la première fois que le modèle apparaît à l'écran ; view, spin, backdrop, ar et alt définissent l'angle initial, la rotation automatique, l'arrière-plan, un bouton de réalité augmentée sur mobile (Quick Look via le fichier USDZ sur iOS) et le texte alternatif. La publication et chaque chargement sont gratuits.
<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 configurateur en 4 peintures représente 4 modèles, soit 400 crédits une seule fois. Les ateliers de covering et de teinte de vitres qui utilisent l'API commandent des modèles 3D de la même manière ; leur témoignage couvre les fichiers et les formats, et la documentation 3D couvre les webhooks, les téléchargements et la dépublication.
CLI, SDK et MCP
- CLI :
npx @meterapp/car-image 3d create --vehicle veh_b6kgpb03d73r9 --color "#1f3a5f" --publish --waitcommande une teinte, attend qu’elle soit prête et affiche le code d’intégration. - SDK :
client.vehicles({ make, model }),client.createImageUrls(…),client.create3dModel({ vehicle }, { color, publish: true })etclient.wait3dModel(id). - MCP : avec
?toolset=all,create_3d_model,get_3d_modeletpublish_3d_modelpermettent à un assistant de commander et de publier une teinte pour un vendeur. La configuration est décrite sur la page MCP.
Questions fréquentes
- L’image montre-t-elle la finition sur laquelle la mensualité est calculée ?
- Non. Le catalogue s’appuie sur la marque, le modèle et l’année : toutes les finitions d’un même millésime donnent donc le même rendu. Indiquez la finition dans le texte de l’offre, à côté de l’image, et ne présentez jamais l’image comme cette finition ni comme une voiture en stock.
- La peinture d’un constructeur coûte-t-elle plus cher qu’une couleur prédéfinie ?
- Non. Chaque peinture est une recoloration d’un même rendu neutre : un code hex coûte donc 1 crédit, comme n’importe lequel des 15 préréglages, et un code hex identique à la pastille d’un préréglage correspond à ce préréglage. Le code hex est appliqué avec cette valeur sRGB exacte sous éclairage studio : comparez donc le rendu avec la pastille de couleur avant la mise en ligne de l’offre.
- Combien coûte un configurateur en 4 peintures ?
- 400 crédits, une seule fois : 100 crédits pour chaque peinture du véhicule. Commander à nouveau un véhicule et une peinture que votre compte possède déjà est gratuit (billing.already_owned vaut true), et la publication, l’interrogation, les téléchargements et chaque chargement d’un modèle publié sont également gratuits.
- Combien de temps faut-il pour un modèle 3D, et que se passe-t-il en cas d’échec ?
- Le premier modèle d’un véhicule prend 10–20 minutes ; chaque peinture supplémentaire du même véhicule réutilise son maillage et prend 1–2 minutes. Un modèle qui échoue est intégralement remboursé, et lorsque la génération 3D atteint sa capacité quotidienne, la requête est refusée avec un délai avant nouvelle tentative, avant toute facturation.
- Un devis PDF peut-il conserver l’image après la fin de l’offre ?
- Oui. Avec un forfait payant, la licence couvre un rendu intégré à ce que votre produit génère pour vos clients, devis ou brochure compris, et un rendu livré dans le cadre du forfait conserve cette licence après la fin du forfait : un devis archivé n’a donc jamais à perdre son image. Générer le rendu d’une nouvelle offre nécessite un forfait actif à ce moment-là.