คู่มือการสร้างที่เขียนจากพฤติกรรมของ API ตามเอกสาร โดยไม่ได้ระบุชื่อลูกค้ารายใด เผยแพร่เมื่อ
ปัญหา: ข้อเสนอแม่นยำ แต่ภาพไม่ตรง
ข้อเสนอลีสซิ่งมีความเฉพาะเจาะจง: รุ่นปีเดียว รุ่นย่อยที่ใช้คำนวณค่างวด สีจากชุดสีปัจจุบันของผู้ผลิต และยอดผ่อนรายเดือนที่มีผลถึงวันที่กำหนด แต่ภาพที่อยู่ข้าง ๆ มักไม่เป็นเช่นนั้น: ภาพประชาสัมพันธ์ของปีที่แล้ว สีที่รถรุ่นนั้นไม่มีจำหน่ายแล้ว หรือตัวถังแบบอื่น เมื่อค่างวดแม่นยำแต่ภาพเป็นเพียงการประมาณ ภาพจึงกลายเป็นส่วนที่ลูกค้าตั้งคำถาม
จากนั้นข้อเสนอเดียวกันจะถูกนำไปใช้ต่อ: บนหน้ารุ่นรถ ใน PDF ใบเสนอราคา ในอีเมล และในเครื่องมือกำหนดสเปก (configurator) ที่ลูกค้าหมุนดูรถได้รอบคัน ทุกช่องทางต้องใช้รถคันเดียวกันในสีเดียวกัน
การผสานรวมมีลักษณะอย่างไร
- ข้อเสนอหนึ่งรายการต่อรุ่นปี โดยใช้ vehicle id ในแคตตาล็อกของปีนั้นเป็นคีย์
- สีจากผู้ผลิตในรูปแบบรหัส hex บนทุกภาพของข้อเสนอ
- ภาพเดียวกันทั้งใน PDF ใบเสนอราคาและในอีเมล ผ่าน signed URL ดังนั้นจึงไม่มีเอกสารหรือตัวเรนเดอร์ใดต้องเก็บคีย์ไว้เลย
- โมเดล 3D หนึ่งรายการต่อหนึ่งสี สำหรับ configurator เผยแพร่เป็นโค้ดฝังสองบรรทัด
ขั้นตอนที่ 1: ผูกข้อเสนอแต่ละรายการกับ vehicle id ของปีรุ่นนั้น
GET /api/v1/vehicles?make=&model= ใช้งานได้ฟรีและเป็นสาธารณะ โดยแสดงทุกปีของรุ่น พร้อม vehicle id ที่คงที่ของแต่ละปี จัดเก็บ id ของรุ่นปีในข้อเสนอไว้คู่กับข้อเสนอนั้น
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 เริ่มใช้งาน ข้อเสนอเหล่านั้นจะใช้ id ของปี 2027 ส่วนข้อเสนอของปี 2026 ยังคงใช้ id เดิม: id ไม่มีวันเปลี่ยน ดังนั้นหน้าเว็บหรือใบเสนอราคาที่สร้างจาก id นั้นจะยังทำงานได้หลังจากเปลี่ยนปีรุ่น แค็ตตาล็อกอ้างอิงตามยี่ห้อ รุ่น และปี ดังนั้นรุ่นย่อยที่ใช้คำนวณค่างวด (เช่น EX-L หรือ Sport Touring) จึงเป็นข้อความในข้อเสนอ ไม่ใช่สิ่งที่ภาพอ้างว่าแสดง
ขั้นตอนที่ 2: สีจากผู้ผลิตตามรหัส hex
สีสำเร็จรูป 15 สีครอบคลุมสีทั่วไป แต่ข้อเสนอต้องใช้สีที่รถมีจำหน่ายจริง นำรหัส hex จากแผ่นสีตัวอย่างของผู้ผลิตมาส่งแบบไม่มีเครื่องหมายใน URL (color=1f3a5f) หรือพร้อม # ใน JSON ("color": "#1f3a5f") hex นับเท่ากับสีสำเร็จรูป คือภาพรถยนต์ 1 ภาพ เพราะสีทุกสีเป็นการเปลี่ยนสีจากมุมมองที่เตรียมไว้มุมเดียว และ 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ขั้นตอนที่ 3: PDF ใบเสนอราคาและอีเมลข้อเสนอผ่าน signed URL
PDF ใบเสนอราคามักเป็น HTML ที่เรนเดอร์ด้วยบริการ PDF หรือ headless browser ให้ใส่ signed URL จาก POST /api/v1/image-urls ไว้ในเทมเพลต ห้ามใส่คีย์: ตัวเรนเดอร์จะโหลดภาพครั้งเดียวแล้วฝังไว้ อายุเริ่มต้น 1 ชั่วโมง จึงเพียงพอ และ 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`,
}
);ขั้นตอนที่ 4: โมเดล 3D สำหรับระบบเลือกสเปกรถ
POST /api/v1/3d พร้อม vehicle id ของข้อเสนอ สีของรถ และ publish: true จะสร้างโมเดลพร้อมเท็กซ์เจอร์ (GLB, USDZ, FBX และเวอร์ชันสำหรับเบราว์เซอร์) และให้ URL ที่ไม่มีคีย์พร้อมโค้ดฝังสองบรรทัด ค่าใช้จ่ายคือ 100 เครดิตต่อรถและสี จากเครดิตที่รวมอยู่ในแพ็กเกจของคุณ เรียกเก็บครั้งเดียว การสั่งรถคันเดิมในสีเดิมอีกครั้งจากบัญชีของคุณไม่มีค่าใช้จ่าย โมเดลแรกของรถแต่ละรุ่นใช้เวลา 10–20 minutes และแต่ละสีถัดไปจะใช้ mesh เดิมและใช้เวลา 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} (ทุก 10–15 วินาทีก็เพียงพอ) หรือส่ง webhook_url พร้อม webhook_secret แล้วรับ POST ที่ลงนามแล้วหนึ่งครั้งเมื่อโมเดลพร้อม data.public.embed.html คือสคริปต์และองค์ประกอบ <car-3d> ให้วางลงในหน้าข้อเสนอ องค์ประกอบนี้จะแสดงภาพโปสเตอร์ทันที และโหลดตัวแสดงผลเมื่อโมเดลเลื่อนเข้ามาในหน้าจอเป็นครั้งแรก view, spin, backdrop, ar และ alt ใช้กำหนดมุมเริ่มต้น การหมุนแบบแท่นหมุน ฉากหลัง ปุ่ม AR บนโทรศัพท์ (Quick Look ผ่าน USDZ บน iOS) และข้อความ alt การเผยแพร่และการโหลดทุกครั้งไม่มีค่าใช้จ่าย
<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>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จะช่วยให้ผู้ช่วย AI สั่งทำและเผยแพร่โมเดลสีรถให้พนักงานขายได้ ดูวิธีตั้งค่าได้ที่หน้า MCP
คำถามที่พบบ่อย
- รูปภาพแสดงรุ่นย่อยที่ใช้คำนวณค่างวดหรือไม่
- ไม่ได้ แคตตาล็อกอ้างอิงตามยี่ห้อ รุ่น และปี ทุกรุ่นย่อยของปีรุ่นเดียวกันจึงเรนเดอร์ออกมาเป็นรถคันเดียวกัน โปรดใส่รุ่นย่อยไว้ในข้อความของข้อเสนอข้างภาพ และอย่าอธิบายภาพว่าเป็นรุ่นย่อยนั้นหรือเป็นรถที่มีในสต็อก
- สีของผู้ผลิตมีราคาแพงกว่าสีพรีเซ็ตหรือไม่
- ไม่ สีทุกสีเป็นการเปลี่ยนสีจากมุมมองที่เตรียมไว้มุมเดียว ดังนั้นรหัส hex จะนับเป็นภาพรถยนต์ 1 ภาพเช่นเดียวกับสีสำเร็จรูป 15 สี และ hex ที่ตรงกับสีตัวอย่างของสีสำเร็จรูปก็คือสีสำเร็จรูปนั้น ค่า hex จะถูกใช้เป็นค่า sRGB ตรงตามนั้นภายใต้แสงสตูดิโอ ดังนั้นโปรดเทียบภาพเรนเดอร์กับแผ่นสีตัวอย่างก่อนเผยแพร่ข้อเสนอ
- เครื่องมือปรับแต่งรถที่มีสี 4 สีมีค่าใช้จ่ายเท่าใด
- 400 เครดิต จ่ายครั้งเดียว: 100 เครดิต ต่อสีแต่ละสีของรถ การสั่งรถและสีที่บัญชีของคุณมีอยู่แล้วซ้ำอีกครั้งไม่มีค่าใช้จ่าย (billing.already_owned เป็น true) และการเผยแพร่ การโพลสถานะ การดาวน์โหลด รวมถึงการโหลดโมเดลที่เผยแพร่แล้วทุกครั้งก็ไม่มีค่าใช้จ่ายเช่นกัน
- โมเดล 3D ใช้เวลานานเท่าใด และหากล้มเหลวจะเป็นอย่างไร
- โมเดลแรกของรถแต่ละรุ่นใช้เวลา 10–20 minutes ส่วนสีเพิ่มเติมแต่ละสีของรถรุ่นเดียวกันจะใช้เมชเดิมซ้ำและใช้เวลา 1–2 minutes โมเดลที่สร้างไม่สำเร็จจะได้รับคืนเต็มจำนวน และเมื่อการสร้าง 3D เต็มความจุรายวันแล้ว คำขอจะถูกปฏิเสธพร้อมระบุเวลาที่ลองใหม่ได้ ก่อนที่จะมีการเรียกเก็บใดๆ
- ไฟล์ PDF ใบเสนอราคายังคงเก็บภาพไว้ได้หลังจากข้อเสนอสิ้นสุดลงหรือไม่
- ได้ สำหรับแพ็กเกจแบบชำระเงิน สิทธิ์การใช้งานครอบคลุมภาพเรนเดอร์ที่อยู่ในสิ่งที่ผลิตภัณฑ์ของคุณสร้างให้ลูกค้า รวมถึงใบเสนอราคาหรือโบรชัวร์ ตราบที่แพ็กเกจยังใช้งานอยู่ ภายใน 30 วันหลังแพ็กเกจสิ้นสุด สำเนาที่จัดเก็บไว้จะต้องถูกลบ หากต้องการเก็บภาพไว้ในใบเสนอราคาอย่างถาวร สามารถซื้อแบบครั้งเดียวเป็น Image Pack ได้