开始使用

Vehicle Imagery API v1.2.0

每个品牌、型号、年份、变体、配置和视图的车辆工作室高质量图像 — 以带有即时格式、尺寸、纵横比、车漆颜色、阴影、透明度、地面和地面镜像的签名 CDN URL交付。

基础 URL

所有端点均位于 https://api.vehicleimagery.com 下。

认证

每个请求都需要在 x-api-key 头中包含您的 API 密钥：

curl -H "x-api-key: YOUR_API_KEY" https://api.vehicleimagery.com/api/brands

您的密钥可能执行的操作（格式、比例、功能、品牌）由 /api/me 返回。文档端点（/api/openapi.json，/api/docs）是公开的，无需密钥。

两种输入方式

认识这辆车吗？ 通过目录导航：品牌 → 车型 → 年份 → 变型 → 配置 → 视图。有实车吗？ 使用查找附加功能 — GET /vin/{vin} 或 GET /plate/{plate} 将 VIN 或车牌号码直接转换为车辆数据，外加该车的工作室图像，并应用真实的车漆颜色（若可用）。附加功能按钥匙启用；/api/me 显示您的钥匙可以做什么。

运作方式

浏览目录 直到一辆车：brand → model → year → variant → trim → view，例如 GET /api/Abarth/124_Spider_Abarth/2016/Basis/base。
解析图像 通过添加视图 + 选项：GET /api/Abarth/124_Spider_Abarth/2016/Basis/base/front_left?format=webp&width=1200 → 返回元数据以及签名的 image_url。
将 image_url 直接嵌入到你的 <img> 中。它是签名且转换锁定的；字节在首次请求时生成，并缓存在 CDN 上，缓存时间为你的计划的 TTL（默认 7 天）。

图像选项

在任何图像请求中附加：format，resolution，ratio，width，height，quality，color，shadow，transparency，ground，mirroring。所有选项自由组合（例如 ?color=wine_red&shadow=true&format=webp&width=1200）。完整的计划过滤集合在 /api/options。

涂装颜色

汽车可以按需重新喷漆 — 反射、铬、玻璃和内饰保持不变；只有油漆改变，符合其光泽（实色或金属色）。/api/colors 列出整个目录，作为 { color_name, color_make } 对：厂房颜色 (black, white, blue, orange, wine_red — color_make: "Vehicleimagery") 适用于每辆车；品牌颜色（例如 Kia *Racing Red*）属于该品牌的汽车。汽车自己的 /colors 端点列出其显示的内容（厂房颜色 + 其品牌的颜色） — 任何活动目录颜色仍可通过 ?color= 在任何车辆上请求。详情：/info/guides/colors 的 *Paint colors* 指南。

阴影、透明度和合成

工作室地面阴影 (shadow=true)、透明剪切 (transparency=true) 和不透明白色交付在交付时为每个外观视图生成 — 整个目录的可用性是一致的。

错误笔记 (非致命)

当无法精确提供请求时，API 并不会失败 — 它会回退到最接近的有效值，并将短代码添加到 errornotes 数组中 (例如 Y01 = 最近使用的年份，S05 = 无法提供阴影)。完整列表请参阅 /api/errornotes。

图像交付与缓存

返回的image_url指向CDN，携带签名和过期时间，并锁定到精确的转换——客户无法篡改它。第一次请求渲染并缓存字节；每次后续请求都直接从缓存中提供。只需将URL放入<img src>中即可。

状态码

200 — 成功。始终检查 errornotes 以获取静默回退。
401 — 缺少或无效的 x-api-key。
403 — 您的计划不允许请求的功能、格式或品牌。
404 — 该路径没有数据。消息准确指出需要检查的内容。

惯例

品牌/型号/变体/配置名称不区分大小写，并接受常见的别名。
年份会自动调整到最近的可用车型
目录端点返回 JSON; 图像字节仅来自签名的 image_url。