Przewodnik wdrożeniowy oparty na udokumentowanym działaniu API; nie wymienia żadnego klienta. Opublikowano .
Problem: oferta jest dokładna, zdjęcie nie
Oferta leasingowa jest konkretna: jeden rocznik, wersja wyposażenia, dla której wyliczono ratę, lakier z aktualnej palety producenta, miesięczna kwota ważna do określonej daty. Zdjęcie obok często takie nie jest: zeszłoroczne zdjęcie prasowe, kolor, w którym samochód nie jest już oferowany, inne nadwozie. Gdy rata jest dokładna, a zdjęcie przybliżone, to właśnie zdjęcie budzi wątpliwości klienta.
Ta sama oferta trafia potem dalej: na stronę modelu, do PDF z kalkulacją, do e-maila i do konfiguratora, w którym klient obraca samochód. Każde z tych miejsc potrzebuje tego samego pojazdu w tym samym lakierze.
Jak wygląda integracja
- Oferta dla każdego rocznika, powiązana z identyfikatorem pojazdu z katalogu dla tego rocznika.
- Lakier producenta jako kod hex na każdym zdjęciu oferty.
- Ten sam obraz w PDF z ofertą i w e-mailu dzięki podpisanym URL-om, więc żaden dokument ani renderer nigdy nie przechowuje klucza.
- Model 3D dla każdego lakieru do konfiguratora, publikowany jako dwuwierszowy kod osadzenia.
Krok 1: powiązanie każdej oferty z id pojazdu dla jej rocznika modelowego
GET /api/v1/vehicles?make=&model= jest bezpłatny i publiczny, a wyświetla wszystkie roczniki modelu, każdy z jego stałym identyfikatorem pojazdu. Identyfikator rocznika modelu z oferty należy zapisać razem z ofertą.
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"
}
]
}
}Gdy ruszą oferty na 2027 rok, otrzymają identyfikator rocznika 2027, a oferty na 2026 zachowają swój: identyfikator nigdy się nie zmienia, więc strona czy wycena na nim oparta działa dalej po zmianie rocznika. Katalog rozróżnia pojazdy po marce, modelu i roku, więc wersja wyposażenia, dla której wyliczono ratę (EX-L, Sport Touring), jest tekstem w ofercie, a nie czymś, co sugeruje obraz.
Krok 2: lakier producenta według kodu hex
Predefiniowane kolory (15) obejmują popularne barwy; oferta wymaga lakieru, w którym samochód jest faktycznie oferowany. Wartość hex należy wziąć z próbki koloru producenta i wysłać bez znaku w URL (color=1f3a5f) lub ze znakiem # w JSON ("color": "#1f3a5f"). Hex liczy się tak samo jak predefiniowany kolor, jako jeden obraz pojazdu, bo każdy lakier to przebarwienie jednego przygotowanego ujęcia, a hex równy próbce predefiniowanego koloru jest tym kolorem i jest buforowany raz.
# 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.webpKrok 3: PDF z kalkulacją i e-mail z ofertą przez podpisane adresy URL
PDF z ofertą to zwykle HTML renderowany przez usługę PDF lub przeglądarkę headless. W szablonie należy umieścić podpisany URL z POST /api/v1/image-urls, nigdy klucz: renderer ładuje obraz raz i go osadza, więc domyślny czas ważności wynoszący 1 godzinę w zupełności wystarcza, a format: "jpg" spłaszcza obraz na białym tle, co pasuje do dokumentu. URL wlicza swój obraz jako obraz pojazdu w miesiącu w momencie wygenerowania.
Klient otwiera e-mail z ofertą wtedy, gdy do niego dotrze. Obraz należy wygenerować z renew: true i ttl_seconds ustawionym na maksimum 7 dni, a renew_days ustawić na liczbę dni pozostałych do końca oferty: odnowienie liczy obraz raz w miesiącu, w którym nastąpi, i nic więcej, jeśli w tym miesiącu był już policzony; spokojne tygodnie nic nie kosztują, a gdy oferta się kończy, URL przestaje się odnawiać i wygasa. W płatnym planie licencja obejmuje render w materiałach, które Państwa produkt tworzy dla klientów, w tym w ofertach.
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`,
}
);Krok 4: model 3D dla konfiguratora
POST /api/v1/3d z identyfikatorem pojazdu z oferty, jego lakierem i publish: true tworzy teksturowany model (GLB, USDZ, FBX i wersja do przeglądarki) i nadaje mu URL-e bez klucza z dwuwierszowym kodem do osadzenia. Kosztuje to 100 kredytów za pojazd i kolor z kredytów zawartych w planie, pobieranych jednorazowo; ponowne zamówienie tego samego pojazdu w tym samym lakierze z tego samego konta jest bezpłatne. Utworzenie pierwszego modelu pojazdu trwa 10–20 minutes, a każdy kolejny lakier wykorzystuje jego siatkę i zajmuje 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
}
}Można odpytywać GET /api/v1/3d/{id} (co 10–15 sekund w zupełności wystarczy) albo przekazać webhook_url wraz z webhook_secret i odebrać jeden podpisany POST, gdy model będzie gotowy. data.public.embed.html to skrypt i element <car-3d>: wystarczy wkleić go na stronę oferty. Element od razu pokazuje obraz podglądu i pobiera przeglądarkę modelu, gdy model po raz pierwszy pojawi się w widoku podczas przewijania; view, spin, backdrop, ar i alt ustawiają kąt początkowy, obrót na obrotnicy, tło, przycisk AR na telefonach (Quick Look przez USDZ w iOS) oraz tekst alternatywny. Publikacja i każde wczytanie są bezpłatne.
<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>Konfigurator na 4 lakierów to 4 modeli, czyli jednorazowo 400 kredytów. Warsztaty oklejania i przyciemniania szyb korzystające z API zamawiają modele 3D w ten sam sposób; ich historia omawia pliki i formaty, a dokumentacja 3D – webhooki, pobieranie i cofanie publikacji.
CLI, SDK i MCP
- CLI:
npx @meterapp/car-image 3d create --vehicle veh_b6kgpb03d73r9 --color "#1f3a5f" --publish --waitzamawia wariant lakieru, czeka na jego wygenerowanie i wypisuje kod osadzenia. - SDK:
client.vehicles({ make, model }),client.createImageUrls(…),client.create3dModel({ vehicle }, { color, publish: true })iclient.wait3dModel(id). - MCP: z
?toolset=allnarzędziacreate_3d_model,get_3d_modelipublish_3d_modelpozwalają asystentowi zamówić i opublikować model w wybranym lakierze dla sprzedawcy. Konfiguracja jest opisana na stronie MCP.
Najczęściej zadawane pytania
- Czy zdjęcie przedstawia wersję wyposażenia, dla której wyliczono ratę?
- Nie. Katalog opiera się na marce, modelu i roczniku, więc każda wersja wyposażenia danego rocznika jest renderowana jako ten sam pojazd. Wersję należy podać w tekście oferty, obok obrazu, i nigdy nie opisywać obrazu jako tej wersji ani jako samochodu dostępnego od ręki.
- Czy lakier producenta kosztuje więcej niż lakier predefiniowany?
- Nie. Każdy lakier to przebarwienie jednego przygotowanego ujęcia, więc hex liczy się jako jeden obraz pojazdu, tak jak każdy z 15 predefiniowanych kolorów, a hex równy próbce predefiniowanego koloru jest tym kolorem. Hex jest stosowany jako dokładna wartość sRGB w oświetleniu studyjnym, dlatego przed publikacją oferty warto porównać render z próbką koloru.
- Ile kosztuje konfigurator z 4 lakierami?
- 400 kredytów, jednorazowo: 100 kredytów za każdy lakier pojazdu. Ponowne zamówienie pojazdu i lakieru, które konto już posiada, jest bezpłatne (billing.already_owned ma wartość true), a publikowanie, odpytywanie, pobieranie i każde wczytanie opublikowanego modelu również są bezpłatne.
- Ile trwa wygenerowanie modelu 3D i co, jeśli się nie powiedzie?
- Pierwszy model pojazdu zajmuje 10–20 minutes; każdy kolejny lakier tego samego pojazdu wykorzystuje jego siatkę 3D i zajmuje 1–2 minutes. Za model, którego nie udało się wygenerować, zwracamy pełną kwotę, a gdy generowanie 3D osiągnie dzienny limit, żądanie zostaje odrzucone z podaniem czasu ponowienia, zanim cokolwiek zostanie naliczone.
- Czy PDF z kalkulacją może zachować zdjęcie po zakończeniu oferty?
- Tak. W planie płatnym licencja obejmuje render w materiałach, które Państwa produkt tworzy dla klientów, w tym w ofercie czy broszurze, dopóki plan jest aktywny; w ciągu 30 dni od jego zakończenia zapisane kopie są usuwane. Obrazy potrzebne na stałe w zapisanych ofertach można kupić jednorazowo jako Image Pack.