画像

署名付きの画像URLを解決します

GET/api/{brand}/{model}/{year}/{variant}/{trim}/{view}

コアエンドポイントです。メタデータと署名済みのimage_urlを返します。これは、直接<img>に埋め込みます。

クエリパラメータとして任意のオプションを追加します。車両に利用できないものやプランで許可されていないものは、最も近い有効な値にフォールバックし、errornotesに報告されます（失敗するのではなく）。

例

?format=webp&width=1200 — WebP、幅1200ピクセル。
?ratio=16:9&format=jpeg — 16:9にパディング。
?mirroring=true — 反射するショールームの床に車が映る。
?transparency=true&format=png — 透明背景に切り抜き。
?color=wine_red — ワインレッドの家の色に塗り替え。
?color=Racing%20Red&shadow=true — キアのカタログペイントにスタジオシャドウを追加。

API v2 アドオン： アドオン画像のある車には、以下の追加オプションが適用されます (lights、background、ヘックス color、windows、plate、fit、size、hotspots) — 例えば、?color=c8102e&windows=dark&size=1080p。アドオンで {view} は、スタジオグループ (hero、steered、extra、drone) でもあり得ます — そのグループの画像をリストします — *API v2 アドオン* を参照。

パスパラメータ

名前	タイプ	説明
`brand` 必須	string	ブランド名または別名（大文字小文字を区別しない）。
`model` 必須	string	モデル名。
`year` 必須	整数	モデル年（4桁）。正確な年が欠落している場合、最も近い利用可能な世代が使用されます（エラーノート `Y01`）
`variant` 必須	string	ボディバリアント。
`trim` 必須	string	トリムレベル
`view` 必須	string	ビュー名 — /api/viewsを参照（例：front、front_left、rear）

クエリパラメータ

名前	タイプ	説明
`format`	string	提供形式。`auto` は WebP を選択。オリジナルは PNG。`pngwebpjpegavifauto`
`resolution`	string	サイズ/品質のプリセット（明示的な幅/品質で上書き）。 `defaultthumbsmallmediumlargefull`
`ratio`	string	アスペクト比にパディングします。 `default` = ネイティブ。 `1:14:33:216:916:102:121:95:43:44:52:39:16`
`width`	整数	幅のラダーにスナップされたピクセル単位の明示的な幅
`height`	整数	ピクセル単位の明示的な高さ
`quality`	整数	エンコーダー品質（40–100）
`color`	string	名前で塗装色を指定します（大文字小文字を区別しません。スペースはURLエンコードしてください、例：`Racing%20Red`）。車は注文に応じて塗り直されます — 仕上げは本物、反射やトリムはそのまま保たれます。車の `/colors` に表示されているセット（ハウスカラー + そのブランドのカラー）をリストします。`/api/colors` のどのアクティブカラーでもリクエストできます。未知の色 → デフォルト塗装 + エラーノート `F04`。他のすべてのオプションと組み合わせられます。 API v2 アドオン: 6桁のヘックス塗装色も、例：`c8102e`。
`shadow`	string	スタジオの地面の影 — 配達時に生成され、すべての外観ビューで利用可能です。`mirroring=true` の場合、車底の影を制御します。`truefalse`
`transparency`	string	透明な切り抜き背景 — 外観のすべてのビューで利用可能（PNG/WebPと併用）。 `truefalse`
`ground`	string	車を地面に停める（透明なバリアントが必要）。 `true`
`mirroring`	string	反射する床。`true` = シャドウ付きアンダーボディ、`clean` = 反射のみ。透明なバリアントが必要です。 `trueclean`
`lights`	string	API v2 アドオン：ヘッドライトをオンまたはオフ (デフォルト `off`)。画像で利用不可 → `off` + エラーノート `L26`。`onoff`
`background`	string	API v2 アドオン： `white` (デフォルト)、`transparent`、または `f4f4f4` のような 6 桁の 16 進数カラー。スタジオ画像のみ (ライフスタイル → エラーノート `B32`)
`windows`	string	API v2 アドオン： `see_through` = 画像のガラス (デフォルト)、`dark` = 透けないプライバシーガラス。利用不可 → エラーノート `W28`。`see_throughdark`
`plate`	string	API v2 アドオン：ナンバープレート — `none` = 画像のまま (デフォルト)、`blank` = 空のプレート、`logo` = プレートにあなたのロゴ (キーで設定; ない場合 → 空白 + エラーノート `N30`)。`noneblanklogo`
`fit`	string	API v2 アドオン：車が `ratio` / `size` ボックスをどのように埋めるか — `contain` はパディング (デフォルト)、`cover` はトリミング。ライフスタイル画像は常にカバー。`containcover`
`size`	string	API v2 アドオン：最も長い辺 — `2k` 2560 px、`1080p` 1920 px、`720p` 1280 px、`540p` 960 px、`360p` 640 px、`thumb` 320 px。`width` / `height` は `size` に優先します。`2k1080p720p540p360pthumb`
`hotspots`	string	API v2 アドオン： `hotspots` をレスポンスに追加 — 画像の興味のあるポイント (リム、ヘッドライト …) を 0–1 の分数として。例えば、インタラクティブビューアー用。`true`

リクエスト

curl "https://api.vehicleimagery.com/api/bmw/m4/2024/coupe/base/front?format=png&resolution=default" \
  -H "x-api-key: YOUR_API_KEY"

200 · 署名付き `image_url`を含む画像メタデータ

[
  {
    "id": 47456,
    "brand": "Abarth",
    "model": "124_Spider_Abarth",
    "year": 2016,
    "variant": "Basis",
    "trim": "base",
    "view": "front_left",
    "resolution": "default",
    "ratio": "default",
    "format": "webp",
    "settings": {
      "color": "default",
      "shadow": false,
      "transparency": false,
      "watermark": false,
      "ground": false,
      "mirroring": false,
      "width": 800
    },
    "image_url": "https://cdn.vehicleimagery.com/source/01KVJC5S0S639G46CASP7EK8HG?f=webp&q=82&w=800&verify=…&expire=…"
  }
]

401 · `x-api-key` がありませんまたは無効です。

{
  "error": "Invalid API key"
}

403 · プランの制限（機能、フォーマット、またはブランドが許可されていない）またはブロックされたリクエスト。

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

404 · 要求されたパスにデータがありません。

{
  "error": "Brand 'Xyz' not found — check /api/brands for valid brands."
}