はじめる

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が返されます。
Embed image_urlを直接<img>に埋め込みます。署名付きで変換ロックされており、バイトは最初のリクエスト時に生成され、プランのTTL（デフォルト7日）でCDNにキャッシュされます。

API v2 オプション：スタジオセット、360°スピン、ライフスタイル（新）

API v2 アドオンのキーを持つユーザーは、新しいスタジオ画像セットも利用できます — 同じカタログで、同じ呼び出しで。accessを/api/meで確認してください：v1 = 標準画像、v2 = アドオン、all = 両方。トリムエンドポイントでは、アドオン画像がある車はgroupsがviewsの隣にリストされます。

標準ビュー (front, front_left … right) — いつもと同じURLです。
スタジオグループ — …/{trim}/{group}は画像のリストを表示し、…/{trim}/{group}/{image}は一つの画像を解決します。
hero — ヒーローショット、三分の二の視点、一部は地面から (8枚の画像)
steered — 前輪を切った状態、3つのカメラの高さから (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}/…は、他の車と同様に動作します。

実車をお持ちですか？ (ベータ)

車の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=を通じて任意の車でリクエストできます。詳細については、*Paint colors*ガイドの/info/guides/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からのみ取得されます。