画像

署名付きの画像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`（グロス）、または仕上げ付きのヘックスカラー：`<finish>_<hex>`、例：`metallic_315fbf`、`matte_283b56`、`carbon_545454`、`chrome_eac972`；メタリック、パール、サテンは効果のためにオプションの2番目の色を取ることができます、例：`metallic_315fbf_5693f9`。仕上げ：`solid`、`metallic`、`pearl`、`satin`、`matte`（または `matt`）、`chrome`、`aluminium`、`carbon`。
`shadow`	string	スタジオの地面の影 — 配達時に生成され、すべての外観ビューで利用可能です。`mirroring=true` の場合、車底の影を制御します。`truefalse`
`transparency`	string	透明な切り抜き背景 — 外観のすべてのビューで利用可能（PNG/WebPと併用）。 `truefalse`
`ground`	string	車を地面に停める（透明なバリアントが必要）。 `true`
`mirroring`	string	反射する床。`true` = シャドウ付きアンダーボディ、`clean` = 反射のみ。透明なバリアントが必要です。 `trueclean`
`lights`	string	API v2アドオン: ヘッドライトのオン・オフ。デフォルト`on`: パラメータがないと、画像はライトがついた状態で表示されます。ライトを消したい場合は、`lights=off`を送信してください。ライトのバリエーションがない画像はライトなしで表示されます。`lights=on`を指定すると、エラーノート`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 add-on: ナンバープレート — `none` = 画像のまま（デフォルト）、`blank` = 空のプレート、`logo` = プレートにあなたのロゴ（キーに設定済み、ない場合 → 空 + エラーノート `N30`）、`text` = `plate_text` のあなたのテキスト（キーに対して有効にする必要があります、詳細は `/api/me` の `addon.plate_text` を参照、そうでない場合はエラーノート `O31`）。 `noneblanklogotext`
`plate_text`	string	API v2 add-on: `plate=text` のテキスト — 最大10文字: 文字、数字、スペース、および `-` `.` `&`。送信した通りにプレートに書かれます（大文字と小文字が保持されます）、中央揃えでプレートが許す限り大きく表示されます。ない、長すぎる、または他の文字 → `400`。
`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`
`version`	string	1つのバージョンからの結果のみ：`v1` = 標準画像、`v2` = API v2 の追加（標準画像にフォールバックしない）。このパラメータがない場合は、キーが許可するすべてのものが取得されます。キーで許可されていない場合 → `403`。`v1v2`

リクエスト

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."
}