API의 문서화된 동작을 바탕으로 작성된 구축 가이드이며, 특정 고객을 언급하지 않습니다. 게시.
문제: 기록에 적힌 차량을 아무도 볼 수 없음
견적 신청서, 보험 계약 기록, 최초 사고 접수는 모두 같은 방식으로 차량을 지칭합니다. 고객이 입력하거나 등록 서류에서 읽어 온 VIN입니다. 이후 사람이 보게 되는 차량 정보는 연식, 제조사, 모델, 그리고 경우에 따라 트림까지의 텍스트뿐입니다. 텍스트 한 줄 옆에서 "고객님의 차량이 맞습니까?"라고 물으면 어떤 차량이든 '예'라는 답이 나오기 쉽습니다.
VIN이 가리키는 모델의 이미지를 보면 고객과 손해사정사가 기록에 올바른 종류의 차량이 적혀 있는지 한눈에 확인할 수 있습니다. 하지만 어떤 차량인지까지 보여줄 수는 없습니다. 렌더는 카탈로그상의 제조사, 모델, 연식을 표현한 스튜디오 일러스트이며 특정 실물 차량을 묘사하지 않습니다. 이 사실 하나가 아래의 전체 통합 방식을 결정합니다.
연동 구조 한눈에 보기
- 접수 시 디코딩합니다. 견적 플로나 보험 계약 시스템에서 VIN을 한 번 무료로 디코딩하고, 카탈로그의 차량 id를 보험 계약과 함께 저장합니다. 해당 계약에 대해 접수된 보험금 청구는 이 id를 그대로 이어받습니다.
- 모든 화면에 하나의 뷰. 대표 각도인
front-3-4를 견적 화면, 보험금 청구 작업 화면, 견적 PDF, 보험 계약 포털에서 같은 박스 하나에 표시하므로 모든 화면이 모델을 같은 방식으로 보여 줍니다. - 키가 아닌 서명된 URL. 브라우저와 PDF 렌더러는 서버에서 발급한 키 없는 URL을 불러옵니다.
- 이미지가 전달할 수 없는 것은 글로. 트림, 옵션, 등록된 색상, 손상, 주행 거리는 텍스트와 사진으로 남기고, 이미지에는 참고용임을 표시합니다.
1단계: VIN을 무료로 디코딩하기
GET /api/v1/vin/{vin}는 무료이며 images:read 권한이 있는 키가 필요합니다. NHTSA vPIC 데이터에서 디코딩된 필드(연식, 제조사, 모델, 트림, 시리즈, 차체 유형, 엔진 및 vPIC가 제공하는 기타 모든 속성)를 반환하며, 카탈로그에 해당 차량이 있으면 고정 id와 바로 사용할 수 있는 image_path를 담은 vehicle 객체도 함께 반환합니다.
curl --fail-with-body \
-H "Authorization: Bearer $CAR_IMAGE_API_KEY" \
"https://carimage.dev/api/v1/vin/WP0AA2A96RS201834"{
"data": {
"vin": "WP0AA2A96RS201834",
"valid": true,
"errors": [],
"suggested_vin": null,
"year": 2024,
"make": "Porsche",
"model": "911",
"trim": "Carrera, Carrera T, Carrera 4",
"series": "Type 992",
"body_class": "Coupe",
"vehicle": {
"id": "veh_78qtwrgh37bkr",
"make": "Porsche",
"model": "911",
"year": 2024,
"image_path": "/api/v1/images/car?vehicle=veh_78qtwrgh37bkr"
},
"source": "vpic-db"
}
}trim을 확인하세요: "Carrera, Carrera T, Carrera 4". 이 VIN의 패턴은 세 가지 트림에 해당하므로 디코딩으로도 보험 계약이 어느 트림을 보장하는지 알 수 없으며, 2024 911의 렌더링으로는 더더욱 알 수 없습니다. 고객에게 트림을 확인받아 series, body_class와 함께 텍스트로 보관하고, 이미지는 모델을 보여 주는 용도로 사용하세요.
- 검사 숫자가 잘못된 VIN도 디코딩되며,
valid: false와 함께 문제 내용이errors에 담깁니다.suggested_vin은 vPIC가 잘못되었다고 판단한 문자를!로 표시하며, 입력하는 사람에게는 이것을 보여 주면 됩니다. - 앞 몇 자리만 입력된 양식에서는 부분 VIN을 보낼 수 있습니다. 최소 5자이며, 알 수 없는 각 자리에는
*를 넣고year는 선택적으로 지정합니다. 404는 vPIC에 해당 패턴의 기록이 없다는 뜻입니다. vPIC는 미국 시장용 차량을 다루므로, 다른 시장의 경우POST /api/v1/images/resolve로 제조사와 모델부터 시작하세요. 이 역시 무료입니다.
2단계: 보험 증권과 청구 건에 차량 id 보관하기
data.vehicle.id를 보험 계약에 일반 문자열로 저장하고, 해당 계약으로 접수되는 모든 청구 건에 복사하세요. 이 id는 결정적이고 영구적입니다. 같은 차량은 모든 배포와 모든 카탈로그 릴리스 이후에도 같은 id를 가지므로 외래 키로 안전하게 사용할 수 있으며, 이후 모든 요청에서는 제조사와 모델을 일일이 적는 대신 vehicle=veh_78qtwrgh37bkr를 지정합니다.
data.vehicle이 null이면 디코딩된 제조사와 모델이 카탈로그에 없다는 뜻입니다. 트레일러와 일부 상용 섀시가 이에 해당합니다. 디코딩된 필드는 그대로 표시할 수 있습니다. 이미지 없이 표시하고, 비슷한 차량 이미지로 대체하지 마세요.
3단계: 청구 서류와 견적 PDF에 동일한 뷰 하나 사용
견적 화면, 보상 처리 워크벤치, 보험 계약 포털은 브라우저 앱이므로 서버에서 POST /api/v1/image-urls로 서명된 URL을 발급합니다. 각 URL은 발급 시점에 해당 이미지를 그달의 차량 이미지로 집계하며, 호출당 최대 50개까지 발급할 수 있고 만료될 때까지 무료로 불러올 수 있습니다. 구도를 한 번 정하고 같은 형태를 재사용하세요. 640×400 박스에 fit: "contain"으로 front-3-4를 넣고, trim에 약간의 padding을 주면 쿠페와 픽업트럭이 박스를 같은 방식으로 채웁니다. 각 URL의 유효 기간은 표시되는 위치에 따라 다릅니다.
- 보험금 청구 처리 화면. 화면을 표시할 때 발급하세요. 기본 유효 기간인 1시간은 한 번의 작업 세션에 충분하며, 다음 날 다시 여는 청구 건에는 새 URL이 발급됩니다.
- 견적 PDF. PDF를 HTML로 렌더링하면 렌더러가 사진을 한 번 불러와 삽입하므로 기본 유효 기간으로 충분하며, PDF 서비스가 귀사의 키를 보유할 일도 없습니다.
format: "jpg"는 사진을 흰색 배경으로 합성하며, 문서에는 이것이 적합합니다. - 보험 증권 포털과 갱신 이메일. 이들은 어떤 유효 기간보다도 오래 사용되므로
renew: true와ttl_seconds: 604800(7일)로 발급하세요. URL은 계속 작동하며, 갱신 시 이미지는 해당 월에 한 번 계산되고 그 달에 이미 계산된 경우에는 추가로 계산되지 않습니다. 허용되는 최대값인renew_days: 365로 1년 보험 기간을 모두 포괄할 수 있습니다.
URL을 발급하는 키에 대시보드에서 허용 출처 목록을 지정하세요. 다른 사이트에서 불러온 URL은 origin_not_allowed와 함께 403을 반환하지만, Referer를 보내지 않는 이메일 클라이언트와 PDF 뷰어에서는 계속 불러올 수 있습니다. 키를 폐기하면 해당 키로 발급한 모든 URL이 무효화됩니다.
import { CarImageClient, type ImageParams } from "@meterapp/car-image-sdk";
const client = new CarImageClient({ apiKey: process.env.CAR_IMAGE_API_KEY });
// Quote or policy intake: the VIN in, the vehicle id and the decoded words on the record. Free.
const { data: decoded } = await client.decodeVin(policy.vin);
policy.vehicleId = decoded.vehicle?.id ?? null; // null: show the decoded text and no picture
policy.trimText = decoded.trim; // "Carrera, Carrera T, Carrera 4": words, never the picture
if (policy.vehicleId) {
// One view, framed once, for every screen and document that shows this policy's car.
const view: ImageParams = {
vehicle: policy.vehicleId, view: "front-3-4", color: policy.paintHex ?? "silver",
width: 640, height: 400, fit: "contain", trim: true, padding: 6,
};
// The claims workbench: a URL for this session, minted when the screen draws.
const { data: [workbench] } = await client.createImageUrls({ ...view, format: "auto" });
// The quote PDF: the HTML-to-PDF renderer loads the URL once and embeds the picture.
const { data: [pdf] } = await client.createImageUrls({ ...view, format: "jpg" });
// The policy portal and the renewal email: one URL that keeps working for the term.
const { data: [portal] } = await client.createImageUrls(
{ ...view, format: "auto" },
{ ttlSeconds: 604800, renew: true, renewDays: 365, idempotencyKey: `policy:${policy.id}:image` }
);
}4단계: 피보험 차량이 아닌 모델로 라벨 붙이기
라벨은 각주에만 두지 말고 사진이 있는 곳에 넣으세요. 대체 텍스트와 이미지 아래 캡션에 넣으면 됩니다. 렌더는 선택한 색상으로 제조사, 모델, 연식을 보여 주며, color는 보험 증권에 기재된 색상(프리셋 이름 또는 임의의 hex)을 따를 수 있습니다. 그래도 그것은 해당 색상의 모델일 뿐, 고객의 차량은 아닙니다.
<figure>
<img src="https://carimage.dev/api/v1/delivery/eyJhbGciOi…" width="640" height="400"
alt="Representative image of a 2024 Porsche 911, not a photo of the insured vehicle">
<figcaption>
2024 Porsche 911 · Coupe · Type 992 · trim on the VIN: Carrera, Carrera T or Carrera 4
<small>Representative image of the model. Not a photo of the insured vehicle.</small>
</figcaption>
</figure>비용과 적합한 요금제
- 무료: VIN 디코딩, resolve, 카탈로그 조회, 그리고 유효 기간 내 서명된 URL의 모든 로드.
- 차량 이미지 1개: 각 차량의 도색과 뷰 조합별로, 전송·발급·갱신 횟수나 크기, 형식에 관계없이 한 달에 한 번만 집계됩니다.
- 월간 차량 이미지: 견적 퍼널에는 다양한 차량이 들어오며, 각 플랜에는 매월 일정 수의 차량 이미지가 포함됩니다. Free 100개, Pro 2,500개, Business 10,000개이며 Enterprise는 협의로 정합니다. 이번 달에 이미 집계된 이미지는 항상 제공되고, 한도를 넘는 요청은 집계되기 전에 402로 응답하므로 견적을 내는 차량 수에 맞춰 플랜을 선택하세요.
유료 플랜에서는 플랜이 활성 상태인 동안, 견적서나 보고서를 포함해 귀사 제품이 사용자에게 제공하는 결과물 안의 렌더가 라이선스 범위에 포함됩니다. 자세한 내용은 라이선스에서 확인하세요.
CLI, SDK 및 MCP
# decode for free and keep the id
npx @meterapp/car-image vin WP0AA2A96RS201834 --json | jq -r .data.vehicle.id
# one renewing URL for the policy's documents, minted once however often intake retries
npx @meterapp/car-image url --vehicle veh_78qtwrgh37bkr --view front-3-4 --width 640 --height 400 \
--fit contain --trim --padding 6 --format auto --ttl 604800 --renew --renew-days 365 \
--idempotency-key policy-88213-image- SDK: 위와 같이
client.decodeVin(vin, { year? })및client.createImageUrls(…)를 사용하고, VIN이 없는 차량에는client.resolve(query)를 사용합니다. - MCP:
decode_vin과create_car_image_urls는 핵심 도구 세트에 포함되어 있어, 보험금 청구 건을 컨텍스트로 가진 어시스턴트가 등록된 VIN으로 "보험 가입 모델 보여 줘"라는 요청에 답할 수 있습니다. 설정 방법은 MCP 페이지에 있습니다.
자주 묻는 질문
- 이 이미지를 피보험 차량의 사진 대신 사용할 수 있나요?
- 아니요. 이는 사진이 아니라 카탈로그상의 제조사, 모델, 연식을 기준으로 한 스튜디오 렌더링이며, 특정 차량을 묘사하지 않습니다. 고객이나 손해사정사가 기록에 올바른 종류의 차량이 지정되어 있는지 확인하는 데 도움이 됩니다. 차량 상태, 손상, 트림, 옵션, 개조 사항은 사진, 검사, 디코딩된 텍스트를 통해 확인해야 하며, 이미지에는 참고용임을 표시해야 합니다.
- 모든 견적서에 사진을 넣으면 비용이 얼마인가요?
- VIN 디코딩은 무료입니다. 이미지는 서명된 URL이 발급되거나 이미지 데이터가 서버로 전달될 때 해당 월의 차량 이미지 하나로 집계되며, 이후 필요한 만큼 제공됩니다. 서명된 URL은 만료 전까지 무료로 불러올 수 있습니다. 갱신되는 URL은 이후 열리는 각 달에 한 번씩 이미지를 집계하며, 아무도 보지 않는 달에는 집계되지 않습니다.
- VIN은 디코딩되는데 vehicle이 null입니다. 어떻게 해야 하나요?
- 디코더가 차량은 인식했지만 카탈로그에 해당 제조사, 모델, 연식 항목이 없는 경우로, 트레일러나 일부 상용차 섀시에서 발생합니다. 디코딩된 필드는 이미지 없이 표시하고, 비슷한 차량으로 절대 대체하지 마세요. 철자가 다를 수 있으니 카탈로그를 검색해 보시고, 정말 없다면 공개 요청 게시판에서 추가를 요청하세요.
- VIN 디코딩은 미국 외 시장의 차량에도 적용되나요?
- 디코더는 NHTSA의 vPIC 데이터를 사용하며, 이 데이터는 미국 시장용으로 제작된 차량을 다룹니다. 따라서 다른 시장의 VIN은 올바르게 입력해도 404를 반환하거나 모델 없이 디코딩될 수 있습니다. 이런 차량은 무료 resolve 엔드포인트에서 제조사, 모델, 연식으로 찾으세요. 카탈로그 자체는 다른 시장의 차명도 포함합니다.
- 청구 파일에 이미지를 얼마나 오래 보관할 수 있나요?
- 요금제가 활성 상태인 동안입니다. 유료 요금제의 라이선스는 견적서나 보고서를 포함해 귀사 제품이 생성하는 결과물 안의 렌더링 이미지에 적용되며, 요금제 종료 후 30일 이내에 저장된 사본은 삭제됩니다. 기록에 이미지를 영구적으로 보관하려면 이미지 팩으로 구매하세요. 렌더링 이미지는 시간이 지나며 개선될 수도 있으므로, 고객이 본 그대로를 보존해야 하는 기록에는 URL이 아닌 파일을 저장하세요.