راهنمای پیاده‌سازی که بر پایهٔ رفتار مستندشدهٔ API نوشته شده است؛ نام هیچ مشتری‌ای در آن نیامده است. منتشرشده در .
مشکل: پیشنهاد دقیق است، اما تصویر نه
یک پیشنهاد لیزینگ مشخص است: یک مدل‌سال، تریمی که قسط بر اساس آن اعلام شده، یک رنگ از پالت فعلی خودروساز، و یک مبلغ ماهانه که تا تاریخ معینی معتبر است. تصویر کنار آن اغلب این‌طور نیست: عکس مطبوعاتی سال گذشته، رنگی که دیگر برای آن خودرو عرضه نمی‌شود، یا بدنه‌ای متفاوت. وقتی قسط دقیق است و تصویر تقریبی، تصویر همان بخشی است که مشتری درباره‌اش تردید میکند.
سپس همان پیشنهاد مسیرهای مختلفی را طی میکند: به صفحه مدل، به PDF استعلام قیمت، به ایمیل و به پیکربندی‌کننده‌ای که مشتری در آن خودرو را می‌چرخاند. هر یک از این‌ها به همان خودرو با همان رنگ نیاز دارد.
یکپارچه‌سازی چگونه است
- یک پیشنهاد برای هر سال مدل، با کلید شناسهٔ خودروی همان سال در کاتالوگ.
- رنگ کارخانه بهصورت کد hex، روی تمام تصاویر پیشنهاد.
- همان تصویر در PDF پیشفاکتور و ایمیل، از طریق URLهای امضاشده، تا هیچ سند یا رندرکننده‌ای هرگز کلیدی را نگه ندارد.
- یک مدل سهبعدی برای هر رنگ برای پیکربندیکننده، که بهصورت یک کد جاسازی دوخطی منتشر میشود.
گام ۱: هر پیشنهاد را به شناسهٔ خودروی مدل‌سال خودش متصل کنید
GET /api/v1/vehicles?make=&model= رایگان و عمومی است و همهٔ سال‌های یک مدل را، هر کدام با شناسهٔ ثابت خودرو، فهرست میکند. شناسهٔ سال مدلِ پیشنهاد را همراه با خود پیشنهاد ذخیره کنید.
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 منتشر میشوند، شناسهٔ 2027 را می‌گیرند و پیشنهادهای 2026 شناسهٔ خود را حفظ می‌کنند: شناسه هرگز تغییر نمی‌کند، بنابراین صفحه یا استعلامی که بر پایهٔ آن ساخته شده، پس از تغییر سال مدل همچنان کار میکند. کلید کاتالوگ برند، مدل و سال است، بنابراین تریمی که قسط بر اساس آن محاسبه شده (یک EX-L، یک Sport Touring) متنی روی پیشنهاد است و هرگز چیزی نیست که تصویر ادعا کند.
گام ۲: رنگ کارخانه‌ای خودروساز، با کد hex
15 رنگ ازپیشتعیینشده رنگهای رایج را پوشش می‌دهند؛ اما یک پیشنهاد، رنگی را می‌خواهد که خودرو واقعاً با آن عرضه میشود. hex را از نمونهرنگ سازنده بردارید و در URL بدون علامت (color=1f3a5f) یا در JSON همراه با # ("color": "#1f3a5f") ارسال کنید. یک hex مانند رنگ ازپیشتعیینشده، یک تصویر خودرو شمرده میشود، زیرا هر رنگ، رنگآمیزی دوبارهٔ یک نمای آمادهشده است؛ و hexی که با نمونهرنگ یک رنگ ازپیشتعیینشده برابر باشد، همان رنگ است و یک بار کش میشود.
# 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گام ۳: PDF استعلام قیمت و ایمیل پیشنهاد، از طریق URLهای امضاشده
PDF استعلام قیمت معمولاً HTMLای است که یک سرویس PDF یا مرورگر headless آن را رندر میکند. در قالب، یک URL امضاشده از POST /api/v1/image-urls قرار دهید، هرگز کلید را: رندرکننده تصویر را یک بار بارگذاری و جاسازی میکند، بنابراین طول عمر پیشفرض ۱ ساعت کاملاً کافی است، و format: "jpg" آن را روی زمینهٔ سفید مسطح میکند که برای سند مناسب است. این URL هنگام ساخته‌شدن، تصویرش را بهعنوان یک تصویر خودروی ماه محاسبه میکند.
ایمیل پیشنهاد هر زمان که مشتری به آن برسد باز میشود. تصویر آن را با renew: true و ttl_seconds در حداکثر 7 روز بسازید و renew_days را برابر روزهای باقی‌ماندهٔ پیشنهاد قرار دهید: هر تمدید تصویر را یک بار در ماهی که در آن رخ میدهد محاسبه میکند و اگر در آن ماه قبلاً محاسبه شده باشد چیزی اضافه نمی‌شود، هفته‌های بی‌بازدید هیچ هزینه‌ای ندارند، و وقتی پیشنهاد تمام شود، URL دیگر تمدید نمی‌شود و منقضی میشود. در پلن پولی، مجوز رندری را پوشش میدهد که درون خروجی محصول شما برای مشتریان قرار دارد، از جمله استعلام قیمت.
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`,
}
);مرحله ۴: یک مدل سهبعدی برای پیکربندیکننده
POST /api/v1/3d با شناسهٔ خودروی پیشنهاد، رنگ آن و publish: true یک مدل بافت‌دار (GLB، USDZ، FBX و یک نسخهٔ مرورگر) می‌سازد و URLهایی بدون کلید همراه با یک کد جاسازی دوخطی به آن میدهد. هزینهٔ آن ۱۰۰ اعتبار برای هر خودرو و رنگ است که از اعتبارهای طرح شما کسر میشود و فقط یک بار دریافت میشود؛ سفارش دوبارهٔ همان خودرو با همان رنگ از حساب شما رایگان است. اولین مدل یک خودرو 10–20 minutes طول میکشد و هر رنگ بعدی از همان مش استفاده میکند و 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
}
}GET /api/v1/3d/{id} را بهطور دوره‌ای بررسی کنید (هر ۱۰ تا ۱۵ ثانیه کافی است)، یا یک webhook_url همراه با webhook_secret ارسال کنید تا وقتی مدل آماده شد، یک درخواست POST امضاشده دریافت کنید. data.public.embed.html شامل اسکریپت و یک عنصر <car-3d> است: آن را در صفحهٔ پیشنهاد قرار دهید. این عنصر بلافاصله تصویر پوستر را نشان میدهد و نمایشگر را نخستین باری که مدل در دید قرار میگیرد بارگیری میکند؛ view، spin، backdrop، ar و alt به‌ترتیب زاویهٔ آغازین، صفحهٔ چرخان، پس‌زمینه، دکمهٔ AR در گوشی‌ها (Quick Look از طریق USDZ در iOS) و متن جایگزین را تنظیم می‌کنند. انتشار و همهٔ بارگذاری‌ها رایگان است.
<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 رنگ یعنی 4 مدل، و فقط یک‌بار ۴۰۰ اعتبار. کارگاه‌های روکش و شیشه‌دودی که از API استفاده می‌کنند، مدل‌های سهبعدی را به همین روش سفارش می‌دهند؛ داستان آن‌ها فایل‌ها و فرمت‌ها را شرح میدهد و مستندات سهبعدی به webhookها، دانلودها و لغو انتشار می‌پردازد.
CLI، SDK و MCP
- CLI:
npx @meterapp/car-image 3d create --vehicle veh_b6kgpb03d73r9 --color "#1f3a5f" --publish --waitیک رنگ سفارش میدهد، منتظر آماده شدن آن می‌ماند و کد جاسازی را چاپ میکند. - SDK:
client.vehicles({ make, model })،client.createImageUrls(…)،client.create3dModel({ vehicle }, { color, publish: true })وclient.wait3dModel(id). - MCP: با
?toolset=all، ابزارهایcreate_3d_model،get_3d_modelوpublish_3d_modelبه دستیار امکان می‌دهند یک رنگ را برای فروشنده سفارش دهد و منتشر کند. راه‌اندازی در صفحه MCP توضیح داده شده است.
پرسش‌های متداول
- آیا تصویر همان تیپی را نشان میدهد که قسط بر اساس آن اعلام شده است؟
- خیر. کاتالوگ بر اساس سازنده، مدل و سال کلیدگذاری میشود، پس همهٔ تریمهای یک سالمدل بهصورت یک خودروی یکسان رندر میشوند. تریم را در متن پیشنهاد، کنار تصویر، بیاورید و هرگز تصویر را بهعنوان آن تریم یا خودرویی موجود در انبار توصیف نکنید.
- آیا رنگ کارخانه گرانتر از رنگهای پیشفرض است؟
- خیر. هر رنگ، رنگآمیزی دوبارهٔ یک نمای آمادهشده است، بنابراین یک hex مانند هر یک از 15 رنگ ازپیشتعیینشده، یک تصویر خودرو شمرده میشود و hexی که با نمونهرنگ یک رنگ ازپیشتعیینشده برابر باشد، همان رنگ است. hex دقیقاً با همان مقدار sRGB زیر نور استودیو اعمال میشود، پس پیش از انتشار پیشنهاد، رندر را با نمونهرنگ مقایسه کنید.
- هزینهٔ یک پیکربندیکننده با 4 رنگ چقدر است؟
- ۴۰۰ اعتبار، بهصورت یکباره: ۱۰۰ اعتبار برای هر رنگ خودرو. سفارش دوبارهٔ خودرو و رنگی که حساب شما از قبل در اختیار دارد رایگان است (billing.already_owned برابر true است) و انتشار، بررسی وضعیت (polling)، دانلودها و هر بار بارگذاری یک مدل منتشرشده نیز رایگان است.
- ساخت یک مدل سهبعدی چقدر طول میکشد و اگر ناموفق باشد چه میشود؟
- ساخت اولین مدل یک خودرو 10–20 minutes طول میکشد؛ هر رنگ بعدیِ همان خودرو از مش آن دوباره استفاده میکند و 1–2 minutes طول میکشد. هزینهٔ مدلی که ناموفق باشد بهطور کامل بازگردانده میشود، و وقتی تولید سهبعدی به ظرفیت روزانهاش رسیده باشد، درخواست پیش از هرگونه کسر هزینه، با اعلام زمان تلاش مجدد، رد میشود.
- آیا PDF استعلام قیمت میتواند پس از پایان پیشنهاد، تصویر را حفظ کند؟
- بله. در طرح پولی، تا زمانی که طرح فعال است، مجوز شامل رندری است که درون خروجی محصول شما برای مشتریان قرار میگیرد، از جمله پیشفاکتور یا بروشور؛ ظرف ۳۰ روز پس از پایان طرح، نسخههای ذخیرهشده حذف میشوند. تصاویری را که برای همیشه در پیشفاکتورهای ذخیرهشده لازم دارید، میتوانید یک بار بهصورت Image Pack بخرید.