Eine Anleitung auf Grundlage des dokumentierten Verhaltens der API; sie nennt keinen Kunden. Veröffentlicht am .
Das Problem: Das Angebot ist exakt, das Bild nicht
Ein Leasingangebot ist konkret: ein Modelljahr, die Ausstattungslinie, auf der die Rate basiert, eine Lackfarbe aus der aktuellen Palette des Herstellers, ein Monatsbetrag, der bis zu einem bestimmten Datum gilt. Das Bild daneben ist es oft nicht: das Pressefoto vom Vorjahr, eine Farbe, in der das Auto nicht mehr angeboten wird, eine andere Karosserie. Wenn die Rate exakt ist und das Bild nur ungefähr, ist das Bild der Teil, den Kunden hinterfragen.
Dasselbe Angebot wandert dann weiter: auf eine Modellseite, in ein Angebots-PDF, in eine E-Mail und in einen Konfigurator, in dem der Kunde das Auto dreht. Jede dieser Stellen braucht dasselbe Fahrzeug in derselben Lackierung.
So sieht die Integration aus
- Ein Angebot pro Modelljahr, verknüpft über die Katalog-Fahrzeug-ID dieses Jahres.
- Die Herstellerlackierung als Hex-Wert, auf jedem Bild des Angebots.
- Dasselbe Bild im Angebots-PDF und in der E-Mail, über signierte URLs, sodass kein Dokument und kein Renderer je einen Schlüssel enthält.
- Ein 3D-Modell pro Lackierung für den Konfigurator, veröffentlicht als zweizeiliges Embed.
Schritt 1: Jedes Angebot der Fahrzeug-ID seines Modelljahres zuordnen
GET /api/v1/vehicles?make=&model= ist kostenlos und öffentlich und listet jedes Jahr eines Modells auf, jeweils mit seiner stabilen Fahrzeug-ID. Speichern Sie die ID des Modelljahrs des Angebots zusammen mit dem Angebot.
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"
}
]
}
}Wenn die Angebote für 2027 live gehen, erhalten sie die ID für 2027, und die Angebote für 2026 behalten ihre: Eine ID ändert sich nie. Eine darauf aufgebaute Seite oder ein darauf aufgebautes Angebot funktioniert also auch nach dem Modelljahreswechsel weiter. Der Katalog ist nach Marke, Modell und Jahr geschlüsselt. Die Ausstattung, für die die Rate kalkuliert wird (ein EX-L, ein Sport Touring), steht deshalb als Text im Angebot und wird nie durch das Bild behauptet.
Schritt 2: die Herstellerlackierung als Hex-Wert
Die 15 Presets decken die gängigen Farben ab; ein Angebot braucht die Lackfarbe, in der das Fahrzeug tatsächlich angeboten wird. Nehmen Sie den Hex-Wert vom Farbmuster des Herstellers und senden Sie ihn ohne Präfix in einer URL (color=1f3a5f) oder mit # in JSON ("color": "#1f3a5f"). Ein Hex-Wert kostet wie ein Preset 1 Credit, weil jede Lackfarbe eine Umfärbung eines neutralen Renderings ist, und ein Hex-Wert, der dem Farbfeld eines Presets entspricht, ist dieses Preset und wird nur einmal gecacht.
# 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.webpSchritt 3: das Angebots-PDF und die Angebots-E-Mail über signierte URLs
Ein Angebots-PDF ist meist HTML, das von einem PDF-Dienst oder einem Headless-Browser gerendert wird. Fügen Sie in die Vorlage eine signierte URL aus POST /api/v1/image-urls ein, niemals den Schlüssel: Der Renderer lädt das Bild einmal und bettet es ein, daher reicht die Standardgültigkeit von 1 Stunde völlig aus, und format: "jpg" legt es auf einen weißen Hintergrund, was zu einem Dokument passt. Die URL kostet bei der Erstellung 1 Credit.
Die Angebots-E-Mail wird geöffnet, wann immer der Kunde dazu kommt. Erzeugen Sie ihr Bild mit renew: true und ttl_seconds auf dem Maximum von 7 Tagen und setzen Sie renew_days auf die verbleibenden Tage des Angebots: Jede weitere Woche, in der die E-Mail geöffnet wird, kostet 1 Credit, Wochen ohne Aufrufe kosten nichts, und wenn das Angebot endet, wird die URL nicht mehr verlängert und läuft ab. In einem kostenpflichtigen Plan deckt die Lizenz ein Rendering in allem ab, was Ihr Produkt für Kunden erstellt, auch in einem Kostenvoranschlag.
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`,
}
);Schritt 4: ein 3D-Modell für den Konfigurator
POST /api/v1/3d mit der Fahrzeug-ID des Angebots, seiner Lackfarbe und publish: true erstellt ein texturiertes Modell (GLB, USDZ, FBX und eine Browser-Version) und stellt es unter URLs ohne Schlüssel mit einem zweizeiligen Embed-Code bereit. Es kostet 100 Credits (1,00 $) pro Fahrzeug und Farbe, einmalig berechnet; dasselbe Fahrzeug in derselben Lackfarbe erneut über Ihr Konto zu bestellen, ist kostenlos. Das erste Modell eines Fahrzeugs dauert 10–20 minutes, jede weitere Lackfarbe nutzt dessen Mesh wieder und dauert 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
}
}Fragen Sie GET /api/v1/3d/{id} ab (alle 10–15 Sekunden genügt), oder übergeben Sie eine webhook_url mit einem webhook_secret und erhalten Sie einen signierten POST, sobald das Modell fertig ist. data.public.embed.html enthält das Skript und ein <car-3d>-Element: Fügen Sie es in die Angebotsseite ein. Das Element zeigt sofort das Vorschaubild und lädt den Viewer, sobald das Modell zum ersten Mal in den sichtbaren Bereich scrollt; view, spin, backdrop, ar und alt legen den Startwinkel, die Drehscheibe, den Hintergrund, eine AR-Schaltfläche auf Smartphones (Quick Look über die USDZ-Datei unter iOS) und den Alt-Text fest. Veröffentlichung und jeder Aufruf sind kostenlos.
<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>Ein Konfigurator mit 4 Lackfarben entspricht 4 Modellen, also einmalig 400 Credits. Folierungs- und Tönungsbetriebe, die die API nutzen, bestellen 3D-Modelle auf dieselbe Weise; ihre Story behandelt die Dateien und Formate, und die 3D-Dokumentation behandelt Webhooks, Downloads und das Zurückziehen von Veröffentlichungen.
CLI, SDK und MCP
- CLI:
npx @meterapp/car-image 3d create --vehicle veh_b6kgpb03d73r9 --color "#1f3a5f" --publish --waitbestellt eine Lackfarbe, wartet darauf und gibt den Embed-Code aus. - SDK:
client.vehicles({ make, model }),client.createImageUrls(…),client.create3dModel({ vehicle }, { color, publish: true })undclient.wait3dModel(id). - MCP: Mit
?toolset=allkann ein Assistent übercreate_3d_model,get_3d_modelundpublish_3d_modeleine Lackierung für einen Verkäufer bestellen und veröffentlichen. Die Einrichtung finden Sie auf der MCP-Seite.
Häufig gestellte Fragen
- Zeigt das Bild die Ausstattungsvariante, auf der die Rate basiert?
- Nein. Der Katalog verwendet Marke, Modell und Jahr als Schlüssel, daher wird jede Ausstattungsvariante eines Modelljahres als dasselbe Fahrzeug gerendert. Nennen Sie die Ausstattung im Angebotstext neben dem Bild, und beschreiben Sie das Bild nie als diese Ausstattungsvariante oder als Fahrzeug auf Lager.
- Kostet ein Herstellerlack mehr als eine vordefinierte Farbe?
- Nein. Jede Lackierung ist eine Umfärbung eines neutralen Renderings, daher kostet ein Hex-Wert 1 Credit wie jedes der 15 Presets, und ein Hex-Wert, der dem Farbmuster eines Presets entspricht, ist dieses Preset. Der Hex-Wert wird als exakt dieser sRGB-Wert unter Studiobeleuchtung angewendet. Vergleichen Sie das Rendering daher mit dem Farbmuster, bevor das Angebot live geht.
- Was kostet ein Konfigurator mit 4 Lackfarben?
- 400 Credits, einmalig: 100 Credits für jede Lackierung des Fahrzeugs. Ein Fahrzeug mit einer Lackierung, das Ihr Konto bereits besitzt, erneut zu bestellen, ist kostenlos (billing.already_owned ist true). Auch Veröffentlichen, Polling, Downloads und jeder Abruf eines veröffentlichten Modells sind kostenlos.
- Wie lange dauert ein 3D-Modell, und was passiert, wenn es fehlschlägt?
- Das erste Modell eines Fahrzeugs dauert 10–20 minutes; jede weitere Lackierung desselben Fahrzeugs verwendet dessen Mesh wieder und dauert 1–2 minutes. Ein fehlgeschlagenes Modell wird vollständig erstattet. Hat die 3D-Generierung ihre Tageskapazität erreicht, wird die Anfrage mit einer Wiederholungszeit abgelehnt, bevor etwas berechnet wird.
- Darf ein Angebots-PDF das Bild behalten, nachdem das Leasingangebot ausgelaufen ist?
- Ja. Mit einem kostenpflichtigen Tarif deckt die Lizenz ein Rendering in allem ab, was Ihr Produkt für Kunden erstellt, einschließlich Angeboten und Broschüren. Ein im Rahmen des Tarifs geliefertes Rendering behält diese Lizenz auch nach Ende des Tarifs, sodass ein gespeichertes Angebot nie sein Bild verliert. Für das Rendering eines neuen Angebots ist zu diesem Zeitpunkt ein aktiver Tarif erforderlich.