依据 API 文档所述行为编写的构建指南，不涉及任何具体客户。 发布于 。
问题所在：记录里写着车型，却没人能看到这辆车
报价单、保单记录和首次损失通知都以同样的方式标识车辆：通过 VIN，由客户输入，或从登记文件中读取。此后人们看到的关于这辆车的一切都是文字：年份、品牌、车型，或许还有配置。在一行文字旁边询问“这是您的车辆吗？”，几乎无论是什么车，对方都会回答“是”。
一张 VIN 所解码车型的图片，能让客户和理赔员一眼确认记录中的车辆类型是否正确。但它无法显示具体是哪一辆车：渲染图是目录中某一品牌、车型和年份的摄影棚示意图，并不描绘任何特定的实体车辆。正是这一点决定了下文的整个集成方式。
集成方式一览
- 在录入时解码。报价流程或保单系统免费解码一次 VIN，并将目录中的车辆 id 与保单一同存储。针对该保单发起的理赔会沿用该 id。
- 处处使用同一视角。在报价页面、理赔工作台、报价 PDF 和保单门户中，都以同一个框展示主图角度
front-3-4，让每个页面以相同方式呈现车型。 - 使用签名 URL，绝不暴露密钥。浏览器和 PDF 渲染器加载由您的服务器生成的无密钥 URL。
- 图片无法表达的，用文字说明。配置、选装、登记颜色、损伤和里程仍以文字和照片呈现，并注明图片仅供参考。
第 1 步：免费解码 VIN
GET /api/v1/vin/{vin} 免费使用，需要具有 images:read 权限的密钥。它会返回来自 NHTSA vPIC 数据的解码字段（年份、品牌、车型、配置、系列、车身类型、发动机以及 vPIC 掌握的所有其他属性）；如果目录中有该车辆，还会返回一个 vehicle 对象，其中包含其稳定 id 和可直接使用的 image_path。
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：至少五个字符，每个未知位置用
*表示，并可选择附带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 个，在过期前可免费加载。构图只需确定一次，之后沿用同样的参数：front-3-4 视角，640×400 的画框，fit: "contain"，再加上 trim 和少量 padding，让轿跑和皮卡以相同方式填满画框。每个 URL 的有效期应取决于它的展示位置：
- 理赔工作台。在界面绘制时生成 URL。默认有效期为 1 小时，足以覆盖一个工作时段；明天重新打开的理赔会获得新的 URL。
- 报价 PDF。当 PDF 由 HTML 渲染生成时，渲染器会加载一次图片并将其嵌入，因此默认有效期完全够用，PDF 服务也永远不会接触到您的密钥。
format: "jpg"会将图片合成到白色背景上，这正适合文档使用。 - 保单门户和续保邮件。这些内容的存续时间超过任何有效期，因此请使用
renew: true和ttl_seconds: 604800（7 天）生成签名 URL。该 URL 持续有效；每次续期只在其所在月份计入一次图片用量，若该月已计入则不再重复计数；而renew_days: 365是允许的最大值，可覆盖为期一年的保单期限。
在控制台中为生成 URL 的密钥设置允许的来源列表：从其他网站加载的 URL 会返回 403 和 origin_not_allowed，而不发送 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 可以与保单上的颜色一致（预设名称或任意十六进制值）。但它仍然只是该漆色的这款车型，而不是客户本人的车。
<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 在有效期内的每次加载。
- 一张车辆图片：每辆车的每种车漆和视角，每月只计一次，无论交付、生成或续期多少次，也不论尺寸和格式。
- 每月车辆图片：报价流程会涉及大量不同车辆，每个套餐每月包含一定数量：免费版 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。