API'nin belgelenmiş davranışına dayanarak yazılmış bir uygulama kılavuzu; hiçbir müşterinin adını vermez. tarihinde yayınlandı.
Sorun: teklif kesin, görsel değil
Bir leasing teklifi nettir: tek bir model yılı, ödemenin hesaplandığı donanım paketi, üreticinin güncel paletinden bir boya rengi, belirli bir tarihe kadar geçerli bir aylık tutar. Yanındaki görsel ise çoğu zaman öyle değildir: geçen yılın basın fotoğrafı, aracın artık sunulmadığı bir renk, farklı bir kasa. Ödeme kesin, görsel yaklaşık olduğunda müşterinin sorguladığı kısım görsel olur.
Aynı kampanya daha sonra farklı yerlere taşınır: bir model sayfasına, bir fiyat teklifi PDF'ine, bir e-postaya ve müşterinin aracı döndürüp incelediği bir yapılandırıcıya. Bunların her biri aynı boya rengindeki aynı aracı gerektirir.
Entegrasyon nasıl görünür
- Model yılı başına bir teklif; anahtarı o yılın katalog araç id'sidir.
- Üreticinin boya rengi hex kodu olarak, teklifin her görselinde.
- Teklif PDF'inde ve e-postada aynı görsel, imzalı URL'ler sayesinde; böylece hiçbir belge ya da oluşturucu anahtar barındırmaz.
- Her boya rengi için bir 3D model: yapılandırıcıda kullanılmak üzere, iki satırlık bir embed kodu olarak yayımlanır.
Adım 1: her teklifi kendi model yılının araç kimliğiyle eşleyin
GET /api/v1/vehicles?make=&model= ücretsiz ve herkese açıktır; bir modelin tüm yıllarını, her birinin sabit araç kimliğiyle (id) birlikte listeler. Teklifin model yılına ait kimliği teklifle birlikte saklayın.
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"
}
]
}
}2027 teklifleri yayına girdiğinde 2027 kimliğini alır, 2026 teklifleri ise kendi kimliklerini korur: bir kimlik asla değişmez, bu yüzden onun üzerine kurulan bir sayfa veya teklif, model yılı değiştikten sonra da çalışmaya devam eder. Katalog marka, model ve yıla göre anahtarlanır; bu nedenle ödemenin teklif edildiği donanım (bir EX-L, bir Sport Touring) teklifte metin olarak yer alır, asla resmin iddia ettiği bir şey olmaz.
Adım 2: üreticinin boya rengi, hex koduyla
15 hazır renk yaygın renkleri kapsar; bir teklif ise aracın gerçekte sunulduğu boyayı ister. Hex değerini üreticinin renk kartelasından alın ve URL'de yalın olarak (color=1f3a5f) veya JSON'da # ile birlikte ("color": "#1f3a5f") gönderin. Her boya hazırlanmış tek bir görünümün yeniden renklendirilmesi olduğundan hex, hazır renkle aynı şekilde bir araç görseli olarak sayılır; bir hazır rengin renk örneğine eşit olan hex o hazır renktir ve bir kez önbelleğe alınır.
# 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.webpAdım 3: fiyat teklifi PDF'i ve kampanya e-postası, imzalı URL'lerle
Bir teklif PDF'i genellikle bir PDF hizmeti veya headless tarayıcı tarafından render edilen HTML'dir. Şablona anahtarı değil, POST /api/v1/image-urls ile alınan bir imzalı URL'yi koyun: render aracı görseli bir kez yükleyip gömer, bu nedenle 1 saatlik varsayılan ömür fazlasıyla yeterlidir ve format: "jpg" görseli beyaz zemin üzerine düzleştirir; bu da belgeye uygundur. URL, oluşturulduğunda görselini ayın bir araç görseli olarak sayar.
Teklif e-postası, müşteri ona ne zaman ulaşırsa o zaman açılır. Görselini renew: true ve 7 günlük üst sınırdaki ttl_seconds ile oluşturun ve renew_days değerini teklifte kalan gün sayısına ayarlayın: bir yenileme, görseli denk geldiği ayda bir kez sayar, o ay zaten sayılmışsa başka bir şey saymaz; sessiz haftalar hiçbir şey saymaz ve teklif sona erdiğinde URL yenilenmeyi bırakır ve süresi dolar. Ücretli bir planda lisans, ürününüzün müşteriler için ürettiği içeriklerdeki (teklif dahil) bir render'ı kapsar.
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`,
}
);4. Adım: konfigüratör için bir 3D model
Teklifin araç kimliği, boyası ve publish: true ile yapılan bir POST /api/v1/3d isteği dokulu bir model (GLB, USDZ, FBX ve tarayıcı sürümü) oluşturur ve ona iki satırlık bir gömme koduyla anahtar içermeyen URL'ler verir. Planınızın içerdiği kredilerden araç ve renk başına 100 kredi tutar ve bir kez ücretlendirilir; aynı aracı aynı boyada hesabınızdan yeniden sipariş etmek ücretsizdir. Bir aracın ilk modeli 10–20 minutes sürer; sonraki her boya onun mesh'ini yeniden kullanır ve 1–2 minutes sürer.
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
}
}GET /api/v1/3d/{id} adresini düzenli olarak sorgulayın (10–15 saniyede bir yeterlidir) ya da bir webhook_secret ile birlikte webhook_url iletin. Model hazır olduğunda imzalı tek bir POST isteği alırsınız. data.public.embed.html, betiği ve bir <car-3d> öğesini içerir; bunu teklif sayfasına yapıştırın. Öğe posteri hemen gösterir, görüntüleyiciyi ise model ilk kez görünür alana kaydırıldığında yükler. view, spin, backdrop, ar ve alt sırasıyla açılış açısını, döner tablayı, arka planı, telefonlardaki AR düğmesini (iOS’ta USDZ üzerinden Quick Look) ve alt metni belirler. Yayınlama ve her yükleme ücretsizdir.
<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>4 renkli bir yapılandırıcı 4 model demektir ve bir kez 400 kredi tutar. API’yi kullanan kaplama ve cam filmi atölyeleri de 3D modelleri aynı şekilde sipariş eder. Dosyaları ve formatları onların hikâyesinde, webhook’ları, indirmeleri ve yayından kaldırmayı ise 3D belgelerinde bulabilirsiniz.
CLI, SDK ve MCP
- CLI:
npx @meterapp/car-image 3d create --vehicle veh_b6kgpb03d73r9 --color "#1f3a5f" --publish --waitbir boya rengi sipariş eder, hazır olmasını bekler ve gömme kodunu yazdırır. - SDK:
client.vehicles({ make, model }),client.createImageUrls(…),client.create3dModel({ vehicle }, { color, publish: true })veclient.wait3dModel(id). - MCP:
?toolset=allilecreate_3d_model,get_3d_modelvepublish_3d_model, bir asistanın satış temsilcisi için bir boya rengini sipariş edip yayımlamasını sağlar. Kurulum adımları MCP sayfasında yer alır.
Sıkça sorulan sorular
- Görsel, taksit teklifinin dayandığı donanım seviyesini gösteriyor mu?
- Hayır. Katalog marka, model ve yıla göre anahtarlanır; bu yüzden bir model yılının her donanım seviyesi aynı araç olarak görselleştirilir. Donanımı teklif metnine, görselin yanına yazın ve görseli asla o donanım ya da stoktaki bir araç olarak tanımlamayın.
- Üreticinin boya rengi, hazır bir renkten daha mı pahalı?
- Hayır. Her boya, hazırlanmış tek bir görünümün yeniden renklendirilmesidir; bu nedenle bir hex, 15 hazır rengin herhangi biri gibi bir araç görseli sayılır ve bir hazır rengin renk örneğine eşit olan hex o hazır renktir. Hex, stüdyo aydınlatması altında tam olarak o sRGB değeri olarak uygulanır; bu yüzden teklif yayına girmeden önce render'ı renk kartelasıyla karşılaştırın.
- 4 boya seçenekli bir yapılandırıcının maliyeti nedir?
- 400 kredi, tek seferlik: aracın her boyası için 100 kredi. Hesabınızda zaten bulunan bir araç ve boyayı yeniden sipariş etmek ücretsizdir (billing.already_owned true olur); yayınlama, yoklama (polling), indirmeler ve yayınlanmış bir modelin her yüklenmesi de ücretsizdir.
- Bir 3D model ne kadar sürer ve başarısız olursa ne olur?
- Bir aracın ilk modeli 10–20 minutes sürer; aynı aracın sonraki her boyası onun 3D ağını yeniden kullanır ve 1–2 minutes sürer. Başarısız olan bir modelin ücreti tamamen iade edilir; 3D üretimi günlük kapasitesine ulaştığında ise talep, herhangi bir ücret alınmadan önce bir yeniden deneme süresiyle reddedilir.
- Bir teklif PDF'i, kampanya sona erdikten sonra da görseli koruyabilir mi?
- Evet. Ücretli bir planda lisans, plan etkin olduğu sürece ürününüzün müşteriler için ürettiği içeriklerdeki (teklif veya broşür dahil) bir görseli kapsar; plan sona erdikten sonraki 30 gün içinde saklanan kopyalar silinir. Saklanan tekliflerde kalıcı olarak ihtiyaç duyduğunuz görseller, tek seferlik bir Image Pack olarak satın alınabilir.