API v2 附加组件

解析摄影棚组图像

GET/api/{brand}/{model}/{year}/{variant}/{trim}/{group}/{image}

API v2 附加组件 — 具有 v2 访问权限的密钥。 一张工作室组合图：hero (主打图，部分从地面拍摄)，steered (转向前轮)，extra (更多角度从三个摄像机高度拍摄，角落也有 30° 和 45°)，drone (俯拍)。这些组合及其图片名称在 *工作室组合：列出其图片* 中有说明。

GET …/{trim} 列出车辆的组别（groups），GET …/{trim}/{group} 列出一个组别的图像（views）。然后在此处解析一个图像。接受所有图像选项，包括插件选项（lights，background，十六进制 color，windows，plate，fit，size，hotspots）。

示例： GET /api/Audi/Q9/2026/SUV/Default/hero → { group: "hero", views: { front_left: true, front_left_ground: true, … } }，然后 GET /api/Audi/Q9/2026/SUV/Default/hero/front_left?color=c8102e&size=1080p&format=webp。

路径参数

名称	类型	描述
`brand` 必需	字符串	品牌名称（附加车辆的更新目录命名）
`model` 必需	字符串	车型名称
`year` 必需	整数	车型年份（四位数）。如果缺少精确年份，则使用最近可用的车型（错误提示 `Y01`）
`variant` 必需	字符串	车身变体
`trim` 必需	字符串	修剪级别
`group` 必需	字符串	摄影棚组：英雄、转向、额外、无人机（见修剪端点的 `groups`）
`image` 必需	字符串	车组图像（见车组的 `views`）

查询参数

名称	类型	描述
`format`	字符串	输出格式。`pngwebpjpegavifauto`
`ratio`	字符串	纵横比。 `1:14:33:216:916:102:121:95:43:44:52:39:16`
`width`	整数	像素宽度。
`color`	字符串	涂装：目录颜色名称、6位十六进制或 `<finish>_<hex>`（例如 `metallic_315fbf`）。
`color_id`	整数	通过 `/api/colors` 使用颜色编号绘制颜色。当一个名称存在多次时使用它：编号是独一无二且永不改变的。优先于 `color`；`0` 是原始涂料。未知或已停用的编号 → 与未知名称相同（默认涂料 + 错误提示 `F04`）。
`shadow`	字符串	摄影棚阴影。`truefalse`
`lights`	字符串	API v2 插件：车灯开关。默认 `on`：不带参数时，图像会带灯，无论图像中是否有灯；发送 `lights=off` 以获取无灯的图像。没有灯光变体的图像直接不带灯；带 `lights=on` 时也会携带错误提示 `L26`。 `onoff`
`background`	字符串	API v2 插件： `white`（默认），`transparent`，或类似 `f4f4f4` 的六位十六进制颜色。仅适用于工作室图像（生活方式 → 错误提示 `B32`）。
`windows`	字符串	API v2 插件： `see_through` = 玻璃，如图所示（默认），`dark` = 隐私玻璃，无法看透。不可用 → 错误提示 `W28`。`see_throughdark`
`plate`	字符串	API v2 插件：车牌 — `none` = 图片中的车牌 (默认)，`blank` = 空白车牌，`logo` = 你的标志在车牌上 (设置在你的密钥上；缺失 → 空白 + 错误提示 `N30`)，`text` = 你自己的文本来自 `plate_text` (必须为你的密钥启用，见 `/api/me` 中的 `addon.plate_text`；否则错误提示 `O31`)。 `noneblanklogotext`
`plate_text`	字符串	API v2 插件：`plate=text` 的文本 — 最多 10 个字符：字母、数字、空格和 `-` `.` `&`。按发送的内容写在车牌上 (保留大小写)，居中并尽可能大。缺失、过长或其他字符 → `400`。
`fit`	字符串	API v2 插件：车辆如何填充 `ratio` / `size` 框 — `contain` 填充（默认），`cover` 裁剪。生活方式图像总是覆盖。`containcover`
`size`	字符串	API v2 插件：最长边 — `2k` 2560 像素，`1080p` 1920 像素，`720p` 1280 像素，`540p` 960 像素，`360p` 640 像素，`thumb` 320 像素。`width` / `height` 优先于 `size`。`2k1080p720p540p360pthumb`
`hotspots`	字符串	API v2 插件：在响应中添加 `hotspots` — 图像中的兴趣点（轮毂、前灯等）以 0–1 的分数表示，例如用于交互式查看器。`true`
`version`	字符串	仅从一个版本获取结果：`v1` = 标准图像，`v2` = API v2 附加部分（无回退到标准图像）。没有它：您的密钥允许的所有内容。您的密钥不允许 → `403`。`v1v2`

请求

curl "https://api.vehicleimagery.com/api/bmw/m4/2024/coupe/base/group/image?format=png&ratio=1:1" \
  -H "x-api-key: YOUR_API_KEY"

200 · 包括签名 `image_url` 的图像元数据。

[
  {
    "id": 900000003,
    "brand": "Audi",
    "model": "Q9",
    "year": 2026,
    "variant": "SUV",
    "trim": "Default",
    "version": "v2",
    "view": "hero/front_left",
    "resolution": "default",
    "ratio": "default",
    "format": "webp",
    "settings": {
      "color": "c8102e",
      "color_id": null,
      "color_manufacture": null,
      "shadow": false,
      "transparency": false,
      "watermark": false,
      "ground": false,
      "mirroring": false,
      "lights": "on",
      "background": "white",
      "windows": "see_through",
      "plate": "none",
      "size": "1080p"
    },
    "image_url": "https://api.vehicleimagery.com/image/3/hero/front-left.webp?color=c8102e&lights=on&h=1920&kid=…&v=…&exp=…&sig=…"
  }
]

401 · 缺失或无效的 `x-api-key`。

{
  "error": "Invalid API key"
}

403 · 计划限制（功能、格式或品牌不允许）或被阻止的请求。

{
  "error": "Mirroring is not allowed by your plan."
}

404 · 请求路径无数据。对于车辆路径，`not_found` 表示不存在的级别，`alternatives` 列出了该级别存在的内容。

{
  "error": "Model '9 series' not found for 'BMW' — check /api/BMW for valid models.",
  "code": "model_not_found",
  "not_found": "model",
  "alternatives": {
    "models": [
      "1 series",
      "2 series",
      "3 series",
      "4 series",
      "5 series"
    ]
  }
}