Hướng dẫn xây dựng được viết dựa trên hành vi đã ghi trong tài liệu của API; không nêu tên khách hàng nào. Đăng ngày .
Vấn đề: ưu đãi thì chính xác, hình ảnh thì không
Một ưu đãi thuê xe rất cụ thể: một năm mẫu xe, phiên bản dùng để báo giá khoản thanh toán, một màu sơn trong bảng màu hiện hành của nhà sản xuất, một con số hàng tháng có hiệu lực đến một ngày nhất định. Còn hình ảnh bên cạnh thường không như vậy: ảnh báo chí năm ngoái, màu xe không còn được cung cấp, kiểu thân xe khác. Khi khoản thanh toán chính xác mà hình ảnh chỉ gần đúng, hình ảnh chính là phần khách hàng nghi ngờ.
Sau đó, cùng một ưu đãi sẽ xuất hiện ở nhiều nơi: trên trang mẫu xe, trong PDF báo giá, trong email, và trong trình cấu hình nơi khách hàng xoay chiếc xe. Mỗi nơi đều cần cùng một chiếc xe với cùng màu sơn.
Quy trình tích hợp diễn ra như thế nào
- Mỗi năm mẫu xe một ưu đãi, gắn với id xe trong danh mục của năm đó.
- Màu sơn của nhà sản xuất dưới dạng mã hex, trên mọi hình ảnh của ưu đãi.
- Cùng một hình ảnh trong file PDF báo giá và email, qua các URL đã ký, nên không tài liệu hay trình render nào phải giữ khóa.
- Một mô hình 3D cho mỗi màu sơn dành cho trình cấu hình, được xuất bản dưới dạng mã nhúng hai dòng.
Bước 1: gắn mỗi ưu đãi với id xe của năm đời tương ứng
GET /api/v1/vehicles?make=&model= miễn phí, công khai và liệt kê mọi năm đời của một mẫu xe, mỗi năm kèm vehicle id ổn định. Hãy lưu id năm đời xe của ưu đãi cùng với ưu đãi đó.
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"
}
]
}
}Khi các ưu đãi 2027 ra mắt, chúng dùng id 2027, còn các ưu đãi 2026 giữ id của mình: id không bao giờ thay đổi, nên trang hoặc báo giá được xây dựng dựa trên id đó vẫn hoạt động sau khi chuyển sang đời xe mới. Danh mục định danh theo hãng, mẫu xe và năm, nên phiên bản dùng để báo giá khoản thanh toán (EX-L, Sport Touring) là văn bản trên ưu đãi, không bao giờ là điều hình ảnh khẳng định.
Bước 2: màu sơn của nhà sản xuất, theo mã hex
15 màu có sẵn bao quát các màu phổ biến; còn một ưu đãi cần đúng màu sơn mà xe thực sự được chào bán. Hãy lấy mã hex từ mẫu màu của nhà sản xuất và gửi mã không kèm dấu trong URL (color=1f3a5f) hoặc kèm # trong JSON ("color": "#1f3a5f"). Mã hex được tính như một màu có sẵn, tức một hình ảnh xe, vì mọi màu sơn đều là bản đổi màu từ một góc nhìn đã được chuẩn bị, và mã hex trùng với mẫu màu của một màu có sẵn chính là màu có sẵn đó, chỉ lưu bộ nhớ đệm một lần.
# 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.webpBước 3: PDF báo giá và email chào giá, qua signed URL
PDF báo giá thường là HTML được render bởi một dịch vụ PDF hoặc trình duyệt headless. Hãy đặt URL có chữ ký từ POST /api/v1/image-urls vào mẫu, tuyệt đối không đặt khóa: trình render tải ảnh một lần rồi nhúng vào, nên thời hạn mặc định 1 giờ là đủ, và format: "jpg" làm phẳng ảnh trên nền trắng, phù hợp cho tài liệu. URL tính ảnh của nó là một ảnh xe của tháng khi được tạo.
Email ưu đãi được mở bất cứ khi nào khách hàng xem đến. Hãy tạo ảnh cho email đó với renew: true và ttl_seconds ở mức tối đa 7 ngày, đồng thời đặt renew_days bằng số ngày còn lại của ưu đãi: mỗi lần gia hạn tính ảnh một lần trong tháng diễn ra gia hạn, và không tính thêm nếu ảnh đã được tính trong tháng đó, những tuần không ai xem không bị tính gì, và khi ưu đãi kết thúc, URL ngừng gia hạn và hết hạn. Với gói trả phí, giấy phép bao gồm bản render nằm trong nội dung sản phẩm của bạn tạo ra cho khách hàng, kể cả báo giá.
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`,
}
);Bước 4: mô hình 3D cho trình cấu hình xe
POST /api/v1/3d với id xe của ưu đãi, màu sơn của xe và publish: true sẽ dựng một mô hình có texture (GLB, USDZ, FBX và một bản dựng cho trình duyệt) và cấp cho mô hình các URL không chứa khóa cùng đoạn mã nhúng hai dòng. Chi phí là 100 tín dụng cho mỗi xe và màu, trừ vào tín dụng mà gói của bạn bao gồm, chỉ tính một lần; đặt lại cùng xe với cùng màu sơn từ tài khoản của bạn thì miễn phí. Mô hình đầu tiên của một xe mất 10–20 minutes, và mỗi màu sơn tiếp theo dùng lại lưới mô hình và mất 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
}
}Thăm dò GET /api/v1/3d/{id} (cứ 10–15 giây một lần là đủ), hoặc truyền webhook_url cùng webhook_secret để nhận một POST có chữ ký khi mô hình sẵn sàng. data.public.embed.html gồm đoạn script và một phần tử <car-3d>: hãy dán nó vào trang ưu đãi. Phần tử này hiển thị ảnh poster ngay lập tức và tải trình xem vào lần đầu tiên mô hình được cuộn vào tầm nhìn; view, spin, backdrop, ar và alt thiết lập góc nhìn ban đầu, bàn xoay, phông nền, nút AR trên điện thoại (Quick Look qua USDZ trên iOS) và văn bản alt. Việc xuất bản và mọi lần tải đều miễn phí.
<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>Một trình cấu hình với 4 màu sơn là 4 mô hình, tính 400 credit một lần. Các cửa hàng dán decal và phim cách nhiệt dùng API cũng đặt mô hình 3D theo cách tương tự; câu chuyện của họ đề cập đến các tệp và định dạng, còn tài liệu 3D đề cập đến webhook, tải xuống và hủy xuất bản.
CLI, SDK và MCP
- CLI:
npx @meterapp/car-image 3d create --vehicle veh_b6kgpb03d73r9 --color "#1f3a5f" --publish --waitđặt một màu sơn, chờ hoàn tất và in ra mã nhúng. - SDK:
client.vehicles({ make, model }),client.createImageUrls(…),client.create3dModel({ vehicle }, { color, publish: true })vàclient.wait3dModel(id). - MCP: với
?toolset=all,create_3d_model,get_3d_modelvàpublish_3d_modelcho phép trợ lý đặt tạo và xuất bản một màu sơn cho nhân viên bán hàng. Hướng dẫn thiết lập có tại trang MCP.
Câu hỏi thường gặp
- Ảnh có thể hiện đúng phiên bản mà khoản thanh toán được báo giá không?
- Không. Danh mục xác định xe theo hãng, mẫu và năm, nên mọi phiên bản của một năm đời xe đều được render như cùng một chiếc xe. Hãy ghi phiên bản trong phần văn bản của ưu đãi, cạnh hình ảnh, và đừng bao giờ mô tả hình ảnh là phiên bản đó hay là xe có sẵn trong kho.
- Màu sơn của nhà sản xuất có đắt hơn màu cài sẵn không?
- Không. Mọi màu sơn đều là bản đổi màu từ một góc nhìn đã được chuẩn bị, nên một mã hex được tính là một hình ảnh xe như bất kỳ màu nào trong 15 màu có sẵn, và mã hex trùng với mẫu màu của một màu có sẵn chính là màu có sẵn đó. Mã hex được áp dụng đúng giá trị sRGB đó dưới ánh sáng studio, vì vậy hãy so sánh bản render với mẫu màu trước khi ưu đãi được đăng.
- Một trình cấu hình với 4 màu sơn có chi phí bao nhiêu?
- 400 tín dụng, một lần: 100 tín dụng cho mỗi màu sơn của xe. Đặt lại một xe và màu sơn mà tài khoản đã sở hữu thì miễn phí (billing.already_owned là true), và việc xuất bản, thăm dò trạng thái, tải xuống cũng như mọi lượt tải mô hình đã xuất bản cũng đều miễn phí.
- Tạo một mô hình 3D mất bao lâu, và nếu thất bại thì sao?
- Mô hình đầu tiên của một xe mất 10–20 minutes; mỗi màu sơn tiếp theo của cùng xe đó dùng lại lưới (mesh) của nó và mất 1–2 minutes. Mô hình tạo thất bại được hoàn tiền đầy đủ, và khi việc tạo 3D đạt công suất tối đa trong ngày, yêu cầu sẽ bị từ chối kèm thời gian thử lại trước khi bị tính phí.
- PDF báo giá có thể giữ hình ảnh sau khi ưu đãi kết thúc không?
- Có. Với gói trả phí, giấy phép bao gồm ảnh render nằm trong những gì sản phẩm của bạn tạo ra cho khách hàng, kể cả báo giá hay tài liệu giới thiệu, trong thời gian gói còn hiệu lực; trong vòng 30 ngày sau khi gói kết thúc, các bản sao đã lưu phải được xóa. Những hình ảnh bạn cần giữ vĩnh viễn trong các báo giá đã lưu có thể mua một lần dưới dạng Image Pack.