开始使用
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）是公开的，无需密钥。
运作方式
- 浏览目录 直到一辆车：
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 天）。
API v2 附加组件：摄影套图、360° 旋转和生活场景（新）
带有 API v2 插件 的密钥还可以获得我们的新工作室图像集 — 在同一目录中，使用相同的调用。检查 access 在 /api/me：v1 = 标准图像，v2 = 插件，all = 两者皆有。在车型配置端点，带有插件图像的车辆在 views 旁边列出 groups：
- 标准视图 (
front,front_left…right) — 与往常一样的 URL。 - 摄影棚组 —
…/{trim}/{group}列出图片，…/{trim}/{group}/{image}解析一个: hero— 主打图，三分之二视角，部分从地面拍摄 (8 张图片)steered— 转向前轮，从三个摄像机高度拍摄 (8 张图片)extra— 更多角度：每个侧面和角落的眼平视角、高角度和低角度，角落也有 30° 和 45° (56 张图片)drone— 俯拍：斜拍、俯视和俯拍 (7 张图片)- 图片名称 说明相机位置：侧面 (
front,front_left,left,rear_right等) 加上_eye(眼平视角),_high(俯视),_low(俯视),_ground(地面视角),_30/_45(30° / 45°角视角),_steep(俯视角度陡峭) 或top(俯拍). 每辆车的数量可能不同;/api/getall和分组端点显示它们. - 360° 转动 —
…/{trim}/360列出环（eye_level，low，high），…/{trim}/360/{ring}返回每一帧及其各自的image_url（转动需要所有这些，按顺序）。 - 生活场景 —
…/{trim}/lifestyle列出场景，…/lifestyle/{scene}列出图片，…/lifestyle/{scene}/{image}解析一张。
每个参考端点都了解附加组件：/api/search 和 /api/getall 包含附加组件车辆（getall 还有它们的 groups），一辆车的 /colors、/features 和 /all 描述了它的附加组件选项，而 /api/options、/api/sizes、/api/views 和 /api/me 增加了一个 addon 部分。所有这些也可以通过稳定 ID 使用（/api/id/{id}/…）。
附加图像有额外选项：lights，background（白色、透明或任意十六进制颜色），color 为十六进制颜色（例如 c8102e），windows=dark，plate（blank 或您的 logo），fit，size 和 hotspots — 请参阅 *解析签名图像 URL*。没有附加组件，这些参数将被忽略，且不列出任何组。
名称与 ID： 所有车辆，标准和附加车辆，均使用相同的目录命名（例如 Mercedes-Benz / C-Class、BMW / 5 series）。2026 年 10 月 5 日之前使用的名称（例如 Mercedes / C-Klasse）仍可解析并返回当前名称。名称中从不包含斜杠：目录中写有斜杠的地方，名称中用连字符（例如 Chevrolet / C-K）。仅在附加车辆中存在的车辆 ID 从 900000000 开始；/api/id/{id}/… 对它们的作用与其他车辆相同。
有真实车辆吗？ *(Beta)*
如果你知道车辆的VIN或登记号码，而不是其目录位置，查找附加组件可以在一次调用中完成两个步骤：GET /vin/{vin} 和 GET /plate/{plate} 解码车辆并返回最接近的目录匹配项，带有签名图像URL，与解码数据一起返回。两者均为每个密钥的选项 — 检查 features.vin 和 features.plate 在 /api/me；没有附加组件，它们返回 403。
图像选项
在任何图像请求中附加：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> 中即可。
新图像按公平队列生成：优先级较高的计划优先处理，同时到达的相同请求只生成一次。新组合的首次加载通常需要几秒钟；响应头X-Cache告诉你它的来源（MISS = 刚生成，HIT / HIT-R2 = 缓存，ORIGINAL = 未经处理的源文件），X-Queue-Wait-Ms显示等待时间。如果同时生成大量新图像，图像 URL 可能会返回503 busy，并附带Retry-After: 5 — 只需几秒钟后重新加载即可。
状态码
200— 成功。始终检查errornotes以获取静默回退。401— 缺少或无效的x-api-key。403— 您的计划不允许请求的功能、格式或品牌。404— 该路径没有数据。消息准确指出需要检查的内容。503— （仅限图片 URL）当前正在生成大量新图片，请在Retry-After中的秒数后重试。
惯例
- 品牌/型号/变体/配置名称不区分大小写，并接受常见的别名。
- 年份会自动调整到最近的可用车型
- 目录端点返回 JSON; 图像字节仅来自签名的
image_url。
