مشکل: مشتری می‌خواهد آن را روی خودروی خودش ببیند
یک کارگاه کاور خودرو (رپ)، یک کارگاه دودی شیشه یا نصاب فیلم محافظ رنگ چیزی می‌فروشد که مشتری تا پایان کار نمی‌تواند آن را ببیند. نمونه‌کارها خودروهای دیگران را نشان میدهند. نمونهٔ رنگ سازنده، متریال را روی یک کارت تخت نشان میدهد. آنچه فروش را قطعی میکند، همان M4 مدل ۲۰۲۱ خودِ مشتری با دقیقاً همان خاکستری ساتنی است که درباره‌اش مردد است، و چنین عکسی وجود ندارد، چون کار هنوز انجام نشده است.
همین کمبود در مراحل بعدی کار هم دیده میشود. برشکار فیلم برای سال مدلی که کتابخانهٔ الگوها هنوز پوشش نمیدهد، طرح کلی تمیزی از سپر جلو می‌خواهد. یک پیکربند خودرو نمای چرخانی از خودرو با رنگ پایه‌ای می‌خواهد که طراح بتواند روی آن رنگآمیزی کند. هر سه به یک چیز نیاز دارند: تصویر استودیویی از برند، مدل و سال مشخص، با رنگ دلخواه و بدون هیچ پس‌زمینه‌ای.
سه روشی که کارگاه‌ها از رندرها استفاده می‌کنند
یکپارچه‌سازی‌های کاور بدنه، دودی شیشه و فیلم محافظ که امروز روی API فعال‌اند، سه کار انجام میدهند و گاهی هر سه را با هم:
- یک پایهٔ سفید، سپس متریال روی آن. سال مدل خودروی مشتری را با
color=whiteروی یک PNG شفاف رندر کنید و رپ، فیلم شیشه یا طرح چاپی را در مرورگر روی آن ترکیب کنید. کانال آلفای PNG همان طرح کلی خودرو است. - رنگ با کد هگز. برای روکش تکرنگ یا رنگآمیزی مجدد، از ترکیب‌سازی صرف‌نظر کنید:
color=686c70خودرو را از پیش با همان رنگ برمی‌گرداند، بی‌آنکه شیشهها و رینگها تغییر کنند، به‌عنوان یک تصویر خودرو، درست مانند یک رنگ از پیش تعریفشده. - مدل سهبعدی برای نمای چرخان.
POST /api/v1/3dفایل‌های GLB، USDZ و FBX بافت‌دار از خودرو با رنگ انتخابی می‌سازد، یک بار برای هر خودرو و رنگ. مدل منتشرشده همراه با یک کد جاسازی دوخطی برای صفحهٔ پیشفاکتور و یک فایل USDZ ارائه میشود که مشتری می‌تواند آن را در آیفون به‌صورت واقعیت افزوده (AR) باز کند.
یکی از کارگاه‌ها دسته‌های کاری خود را به‌جای کد از طریق کانکتور ChatGPT اجرا میکند؛ این الگوی چهارمی است که در ادامه بخشی جداگانه به آن اختصاص داده‌ایم.
یک رندر پایهٔ سفید و متریال روی آن
کاور جایگزین رنگ بدنه میشود، پس با کمترین رنگ ممکن شروع کنید. color=white روشن‌ترین بدنهٔ خنثی را با حفظ کامل سایه‌پردازی استودیویی ارائه میدهد. نمای مستقیم side بیشترین سطح کناری بدنه و کمترین اعوجاج پرسپکتیو را نشان میدهد، و این همان چیزی است که پیش‌نمایش متریال لازم دارد. png (یا webp) را درخواست کنید تا کانال آلفا حفظ شود، و بزرگ‌ترین اندازه، یعنی 1024، را انتخاب کنید تا امکان بزرگ‌نمایی پیش‌نمایش وجود داشته باشد.
# the customer's exact model year, in white: the base every material goes on top of
curl --fail-with-body -H "Authorization: Bearer $CAR_IMAGE_API_KEY" \
"https://carimage.dev/api/v1/images/car?vehicle=veh_0ta0ejj0qad2w&view=side&color=white&w=1024&format=png" \
-o m4-side-white.png
# a solid-color wrap or a factory paint, by hex: the API recolors the paint and leaves glass, trim and wheels alone
curl --fail-with-body -H "Authorization: Bearer $CAR_IMAGE_API_KEY" \
"https://carimage.dev/api/v1/images/car?vehicle=veh_0ta0ejj0qad2w&view=side&color=686c70&w=1024&format=png" \
-o m4-side-nardo.pngبرای یک متریال بافت‌دار، ترکیب‌سازی فقط چند خط کد canvas است: رندر یک بار به‌عنوان ماسک کشیده میشود، متریال فقط در محدوده خودرو رنگآمیزی میشود و رندر دوباره در حالت multiply کشیده میشود تا سایه‌روشن‌ها و بازتاب‌هایش از میان متریال دوباره نمایان شوند.
// A textured material (carbon, chrome, a printed design) goes on in the browser.
// The white render is the mask: paint the material only where the car is, then let
// the render's own shading through.
const car = await loadImage(whiteBaseUrl); // transparent PNG from the API
const ctx = canvas.getContext("2d");
canvas.width = car.width;
canvas.height = car.height;
ctx.drawImage(car, 0, 0);
ctx.globalCompositeOperation = "source-atop"; // keep the car's alpha
ctx.fillStyle = ctx.createPattern(materialSwatch, "repeat");
ctx.fillRect(0, 0, canvas.width, canvas.height);
ctx.globalCompositeOperation = "multiply"; // shading, reflections and panel lines come back
ctx.drawImage(car, 0, 0);
// The whole silhouette is covered, glass and wheels included: the API ships the car's
// alpha, not per-panel masks. Good enough for a quote; a solid color should use color=<hex> instead.تطبیق رنگ بدنه یا رنگ رپ با کد hex
از زمانی که رنگ‌ها به رنگآمیزی دوبارهٔ یک رندر خنثی تبدیل شدند، color علاوه بر 15 نام رنگ آماده، هر کد hex شش‌رقمی را هم می‌پذیرد: color=686c70 بدون علامت در URL و "color": "#686c70" در JSON. نمونهرنگ سازنده یا کد رنگ کارخانه‌ای خودروی مشتری را پیدا کنید و آن را ارسال کنید. رنگآمیزی دوباره فقط روی رنگ بدنه اعمال میشود، بنابراین شیشه، چراغ‌ها، تزئینات و رینگها دستنخورده باقی می‌مانند؛ و این دقیقاً تفاوت پیش‌نمایش رپ با یک عکس رنگ‌شده است. هر کد hex یک نسخهٔ کش‌شدهٔ دیگر و یک تصویر خودروی ماه است، پس پالتی از بیست گزینه برای یک خودرو در یک نما برابر بیست تصویر خودرو است.
یک مدل سهبعدی برای نمایش چرخشی و واقعیت افزوده (AR)
وقتی صفحهٔ استعلام قیمت نیاز دارد خودرو بچرخد، یک مدل سفارش دهید. POST /api/v1/3d شناسهٔ خودرو و یک رنگ را می‌گیرد، ۱۰۰ اعتبار کسر میکند و یک GLB بافت‌دار، نسخه‌ای از آن برای مرورگر، یک USDZ و یک FBX را به‌همراه یک تصویر بندانگشتی می‌سازد. نخستین مدل هر خودرو 10–20 minutes طول می‌کشد؛ برای هر رنگ دیگرِ همان خودرو، همان مش در 1–2 minutes دوباره بافتدهی میشود. سفارش خودرو و رنگی که از قبل در اختیار دارید رایگان است (billing.already_owned: true)، بنابراین یک کارگاه می‌تواند پیکربند خود را برای همهٔ سفارش‌ها بر پایهٔ همان مدل پایهٔ سفید بنا کند.
curl -X POST https://carimage.dev/api/v1/3d \
-H "Authorization: Bearer $CAR_IMAGE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: wrap-quote-4471" \
-d '{"vehicle": "veh_0ta0ejj0qad2w", "color": "white", "publish": true}'{
"data": {
"id": "8c1d6b8e-2b4a-4f6e-9a2e-1f3c5d7e9b01",
"object": "3d_model",
"status": "queued",
"progress": 0,
"vehicle": {
"id": "veh_0ta0ejj0qad2w",
"make": "bmw",
"model": "m4",
"year": 2021
},
"color": "white",
"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,
"credits_remaining": 24900,
"already_owned": false
},
"request_id": "req_01j9y…"
}با publish: true مدل حتی پیش از آماده شدن، URLهای بدون کلید روی CDN ما و یک کد جاسازی دریافت میکند؛ این عنصر تا رسیدن فایل‌ها پیشرفت کار را نشان میدهد. view را برای نمای آغازین روی هر یک از نه زاویهٔ دوربین تنظیم کنید، spin را برای صفحهٔ چرخان، backdrop را برای کف استودیو، و ar را تا فایل USDZ به آیفون‌ها و GLB به اندروید از طریق نمایشگر AR خود مرورگر ارائه شود. فایل FBX برای طراح است: آن را در Blender یا یک ابزار طراحی روکش خودرو باز کنید، طرح را روی UVها بکشید، و مشتری طرح خودش را روی خودروی خودش می‌بیند.
<script src="https://carimage.dev/embed/3d.js" async></script>
<car-3d model="m3d_…" view="front-3-4" spin backdrop="studio" ar alt="2021 BMW M4 in white"></car-3d>اجرای یک دسته از ChatGPT یا Claude
همه کسب‌وکارها توسعه‌دهنده ندارند، و یکی از پرکارترین یکپارچه‌سازی‌های این API، اپراتوری است که از یک دستیار هوش مصنوعی رندر درخواست میکند. https://carimage.dev/api/mcp را به‌عنوان یک connector اضافه کنید (ChatGPT و Claude از طریق OAuth وارد میشوند و کاربر مجوزها را روی صفحه تأیید میکند) تا دستیار به همان ابزارهایی دسترسی پیدا کند که یک برنامه دارد: resolve_vehicle برای تبدیل "2014 Audi S3 cabriolet, grey, side" به پارامترهای دقیق، get_car_image برای یک رندر، create_car_image_urls برای حداکثر پنجاه signed URL در یک فراخوانی، و create_3d_model برای نمای چرخان.
دو نکته باعث میشود پردازش دسته‌ای از طریق دستیار به‌خوبی پیش برود:
- برای هر دسته یک
idempotency_keyارسال کنید. دستیارها درخواست را تکرار می‌کنند. با داشتن کلید، فراخوانی تکراریcreate_car_image_urlsهمان نتیجهٔ اول را برمی‌گرداند (idempotent_replayed: true) و هیچ هزینه‌ای ثبت نمی‌شود. - علاوه بر محدودیت نرخ، بودجهٔ رندر را هم در نظر بگیرید. نماهایی از خودرو که تاکنون کسی درخواستشان نکرده، ابتدا باید آماده شوند و آماده‌سازی آنها از سهم روزانهٔ حساب از ظرفیت آماده‌سازی کم میکند (10% در Pro). اجرای چند صد خودروی جدید در سه نما می‌تواند به این سقف برسد؛ در این صورت ابزار با یک زمان تلاش مجدد و
reset_atپاسخ میدهد، هزینه‌ای کسر نمی‌شود و تصاویر کش‌شده همچنان ارائه میشوند. اجرا را در یکی دو شب پخش کنید، یا برای سهم بیشتر به Business ارتقا دهید.
راه‌اندازی برای هر کلاینت و فهرست کامل ابزارها در صفحهٔ MCP آمده است.
CLI، SDK و MCP
# the white base and a hex paint, straight to files
npx @meterapp/car-image get --vehicle veh_0ta0ejj0qad2w --view side --color white --width 1024 --out m4-side-white.png
npx @meterapp/car-image get --vehicle veh_0ta0ejj0qad2w --view side --color 686c70 --width 1024 --out m4-side-nardo.png
# the 3D model: published at once, polled until ready, every file downloaded
npx @meterapp/car-image 3d create --vehicle veh_0ta0ejj0qad2w --color white --publish --wait --out ./modelsimport { CarImageClient } from "@meterapp/car-image-sdk";
const client = new CarImageClient({ apiKey: process.env.CAR_IMAGE_API_KEY });
// 100 credits the first time. Ordering the same vehicle in the same color again
// answers billing.already_owned: true and charges nothing.
const { data: model } = await client.create3dModel({ vehicle: "veh_0ta0ejj0qad2w" }, { color: "white", publish: true });
const ready = await client.wait3dModel(model.id, { onProgress: (m) => console.log(m.stage, m.progress) });
// FBX for the designer's tool of choice, USDZ for the customer's iPhone, glb_web for the page.
const fbx = await client.download3dModel(ready.id, "fbx");
const embedHtml = ready.public?.embed.html;- MCP:
get_car_imageوcreate_car_image_urlsدر مجموعه‌ابزار اصلی، وcreate_3d_model،get_3d_modelوpublish_3d_modelبا?toolset=all؛ هر ابزار تصویر،vehicleو یکcolorهگز دریافت میکند. - مستندات 3D به webhookها (یک POST امضاشده هنگام آماده شدن مدل)، حجم فایل‌ها و همه ویژگی‌های embed می‌پردازد؛ بخش رنگ‌ها در صفحه Images قواعد رنگ بدنه را توضیح میدهد.
پرسش‌های متداول
- آیا رنگ hex سفارشی گرانتر از رنگهای از پیش تعریفشده است؟
- خیر. هر رنگ، رنگآمیزی مجدد یک نمای آمادهشده از همان خودرو است، بنابراین یک رنگ پیشفرض، یک کد رنگ کارخانه که پیدا کردهاید و نمونهرنگ یک تولیدکنندهٔ روکش خودرو هر کدام یک تصویر خودرو حساب میشوند. کد hex که با نمونهرنگ یک رنگ پیشفرض برابر باشد، همان رنگ پیشفرض است.
- آیا رندر برای برش فیلم بهاندازهٔ کافی دقیق است؟
- خیر. رندرها تصاویر استودیویی از برند، مدل و سال هستند، نه دادههای CAD یا عکسهای رسمی کارخانه: کاتالوگ تریمها را از هم جدا نمیکند و خطوط پنلها ممکن است بین دو نمای یک خودرو متفاوت باشد. از آنها برای نشان دادن خودرو به مشتری و برآورد قیمت کار استفاده کنید؛ الگوهای برش را از روی قالب یا خود خودرو تهیه کنید.
- آیا میتوانیم خودرو را بدون رنگ، یا فقط شیشهها را دریافت کنیم؟
- نزدیکترین گزینه به یک بوم خالی، color=white روی PNG شفاف است و کانال آلفای PNG همان سیلوئت خودرو است. API ماسک جداگانه برای هر پنل یا شیشه ارائه نمیدهد. برای کاور تکرنگ، بگذارید color=<hex> کار را انجام دهد: رنگ بدنه را تغییر میدهد و شیشه، تزئینات و رینگها را دستنخورده باقی میگذارد.
- برای پیشفاکتور دودی شیشه یا PPF از کدام نماها باید استفاده کرد؟
- نماهای مستقیم: side (یا side-right) برای شیشههای درها و بدنهٔ کناری، front برای نوار شیشهٔ جلو، کاپوت و سپر، و rear برای شیشهٔ عقب. نماهای سهرخ همانهایی هستند که مشتریان به آنها واکنش نشان میدهند، پس از front-3-4 برای تصویر اصلی و از نماهای مستقیم در کنار اقلام فاکتور استفاده کنید.
- آیا مالکیت مدل سهبعدی با ماست؟
- این مدل نیز مانند رندرها دارای مجوز است: برای هر خودرو و رنگ در هر حساب فقط یکبار پرداخت میشود، سفارش مجدد آن رایگان است و میتوانید آن را در محصول خود استفاده کرده و روی سرورهای خود نگه دارید، حتی پس از پایان پلن. هر رنگ دیگر از خودرویی که از قبل در اختیار دارید، همان mesh را بافتدهی مجدد میکند و انتشار، بدون هزینه، URLهای بدون نیاز به کلید و یک کد embed برای مدل فراهم میکند.