Una guía de implementación escrita a partir del comportamiento documentado de la API; no menciona a ningún cliente. Publicado el .
El problema: la oferta es exacta, la imagen no
Una oferta de leasing es concreta: un año de modelo, la versión sobre la que se calcula la cuota, una pintura de la paleta actual del fabricante y una cifra mensual válida hasta una fecha. La imagen que la acompaña a menudo no lo es: la foto de prensa del año pasado, un color en el que el coche ya no se ofrece o una carrocería distinta. Cuando la cuota es exacta y la imagen es aproximada, la imagen es lo que el cliente pone en duda.
Después, la misma oferta circula: a una página de modelo, a un PDF de presupuesto, a un correo y a un configurador donde el cliente hace girar el coche. Cada uno de ellos necesita el mismo vehículo con la misma pintura.
Cómo es la integración
- Una oferta por año de modelo, con el id de vehículo del catálogo de ese año como clave.
- La pintura del fabricante como hex, en cada imagen de la oferta.
- La misma imagen en el PDF de la oferta y en el correo, mediante URL firmadas, para que ningún documento ni motor de renderizado tenga nunca una clave.
- Un modelo 3D por color de pintura para el configurador, publicado como una inserción de dos líneas.
Paso 1: asocie cada oferta al id de vehículo de su año de modelo
GET /api/v1/vehicles?make=&model= es gratuito y público, y enumera todos los años de un modelo, cada uno con su id de vehículo estable. Guarde el id del año de modelo de la oferta junto con la 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"
}
]
}
}Cuando se publiquen las ofertas de 2027, usarán el id de 2027, y las ofertas de 2026 conservarán el suyo: un id nunca cambia, así que una página o un presupuesto creado sobre él sigue funcionando después del cambio de año de modelo. El catálogo se indexa por marca, modelo y año, así que el acabado sobre el que se calcula la cuota (un EX-L, un Sport Touring) es texto de la oferta, nunca algo que afirme la imagen.
Paso 2: la pintura del fabricante, en hex
Los 15 colores predefinidos cubren los colores habituales; una oferta necesita la pintura en la que realmente se ofrece el coche. Tome el hex de la muestra de color del fabricante y envíelo sin más en una URL (color=1f3a5f) o con su # en JSON ("color": "#1f3a5f"). Un hex tiene el mismo coste de 1 crédito que un color predefinido, porque cada pintura es un recoloreado de un único render neutro, y un hex igual a la muestra de un color predefinido es ese mismo color, almacenado en caché una sola vez.
# 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.webpPaso 3: el PDF del presupuesto y el correo de la oferta, mediante URL firmadas
Un PDF de presupuesto suele ser HTML renderizado por un servicio de PDF o un navegador headless. Ponga en la plantilla una URL firmada de POST /api/v1/image-urls, nunca la clave: el renderizador carga la imagen una vez y la incrusta, así que la vida útil predeterminada de 1 hora es más que suficiente, y format: "jpg" la aplana sobre fondo blanco, lo que conviene a un documento. La URL cuesta 1 crédito al generarse.
El email de la oferta se abre cuando el cliente llega a él. Genere su imagen con renew: true y ttl_seconds al máximo de 7 días, y fije renew_days en los días que le quedan a la oferta: cada semana adicional en la que se abre el email cuesta 1 crédito, las semanas sin actividad no cuestan nada y, cuando termina la oferta, la URL deja de renovarse y caduca. Con un plan de pago, la licencia cubre un render dentro de lo que su producto genera para los clientes, incluido un presupuesto.
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`,
}
);Paso 4: un modelo 3D para el configurador
POST /api/v1/3d con el id del vehículo de la oferta, su pintura y publish: true genera un modelo texturizado (GLB, USDZ, FBX y una versión para navegador) y le asigna URL sin clave con un código de inserción de dos líneas. Cuesta 100 créditos (1,00 US$) por vehículo y color, con un único cargo; volver a pedir el mismo vehículo con la misma pintura desde su cuenta es gratis. El primer modelo de un vehículo tarda 10–20 minutes, y cada pintura adicional reutiliza su malla y tarda 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
}
}Consulte GET /api/v1/3d/{id} periódicamente (cada 10–15 segundos es suficiente), o pase un webhook_url con un webhook_secret y reciba un único POST firmado cuando el modelo esté listo. data.public.embed.html contiene el script y un elemento <car-3d>: péguelo en la página de la oferta. El elemento muestra el póster de inmediato y carga el visor la primera vez que el modelo aparece en pantalla; view, spin, backdrop, ar y alt definen el ángulo inicial, la plataforma giratoria, el fondo, un botón de realidad aumentada en móviles (Quick Look mediante el USDZ en iOS) y el texto alternativo. La publicación y todas las cargas son gratuitas.
<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 configurador con 4 pinturas son 4 modelos, 400 créditos una sola vez. Los talleres de vinilado y tintado de lunas que usan la API piden modelos 3D del mismo modo; su historia trata los archivos y los formatos, y la documentación de 3D trata los webhooks, las descargas y la despublicación.
CLI, SDK y MCP
- CLI:
npx @meterapp/car-image 3d create --vehicle veh_b6kgpb03d73r9 --color "#1f3a5f" --publish --waitsolicita un color, espera a que esté listo e imprime el código para insertarlo. - SDK:
client.vehicles({ make, model }),client.createImageUrls(…),client.create3dModel({ vehicle }, { color, publish: true })yclient.wait3dModel(id). - MCP: con
?toolset=all,create_3d_model,get_3d_modelypublish_3d_modelpermiten que un asistente encargue y publique un modelo 3D en un color concreto para un vendedor. La configuración está en la página de MCP.
Preguntas frecuentes
- ¿La imagen muestra la versión sobre la que se cotiza la cuota?
- No. El catálogo se basa en la marca, el modelo y el año, así que todas las versiones de un año de modelo se renderizan como el mismo vehículo. Indique la versión en el texto de la oferta, junto a la imagen, y nunca describa la imagen como esa versión ni como un coche en stock.
- ¿Cuesta más una pintura del fabricante que un color predefinido?
- No. Cada pintura es un recoloreado de un único render neutro, así que un hex cuesta 1 crédito, como cualquiera de los 15 colores predefinidos, y un hex igual a la muestra de un color predefinido es ese mismo color. El hex se aplica con ese valor sRGB exacto bajo iluminación de estudio, así que compare el render con la muestra de color antes de publicar la oferta.
- ¿Cuánto cuesta un configurador con 4 colores de pintura?
- 400 créditos, una sola vez: 100 créditos por cada pintura del vehículo. Volver a pedir un vehículo y una pintura que su cuenta ya tiene es gratis (billing.already_owned es true), y la publicación, las consultas de estado, las descargas y cada carga de un modelo publicado también son gratis.
- ¿Cuánto tarda un modelo 3D y qué pasa si falla?
- El primer modelo de un vehículo tarda 10–20 minutes; cada pintura adicional del mismo vehículo reutiliza su malla y tarda 1–2 minutes. Si un modelo falla, se reembolsa por completo, y cuando la generación 3D alcanza su capacidad diaria, la solicitud se rechaza con un tiempo de reintento antes de cobrar nada.
- ¿Puede un PDF de presupuesto conservar la imagen cuando termina la oferta?
- Sí. Con un plan de pago, la licencia cubre un render incluido en lo que su producto genera para sus clientes, como un presupuesto o un folleto, y un render entregado con el plan conserva esa licencia aunque el plan termine, así que un presupuesto guardado nunca pierde su imagen. Para crear el render de una oferta nueva se necesita un plan activo en ese momento.