Начать

Vehicle Imagery API v1.2.0

Студийные изображения автомобилей для каждой марки, модели, года, варианта, комплектации и вида — доставляются в виде подписанных URL-адресов CDN с форматированием, размером, соотношением сторон, цветом краски, тенью, прозрачностью, заземлением и отражением в полу на лету.

Базовый URL

Все конечные точки работают под https://api.vehicleimagery.com

Аутентификация

Каждый запрос требует ваш ключ API в заголовке x-api-key.

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 /vin/{vin} или GET /plate/{plate} превращают VIN или номер регистрации в данные автомобиля *и* студийные изображения этой машины, с реальным цветом краски, если это возможно. Дополнительные функции активируются по ключу; /api/me показывает, что может ваш.

Как это работает

Перемещайтесь по каталогу до одного автомобиля: 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 дней).

Опции изображения

Добавьте к любому запросу изображения: 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 endpoint машины перечисляет, что отображается для неё (цвета компании + цвета её бренда) — любой активный цвет каталога всё ещё можно запросить на любой машине через ?color=. Подробности: руководство *Цвета краски* по адресу /info/guides/colors

Тени, прозрачность и композитинг

Тени основания студии (shadow=true), прозрачные вырезки (transparency=true) и непрозрачная белая доставка производятся в момент доставки для каждого внешнего вида — доступность равномерна по всему каталогу.

Ошибки (не фатальные)

Когда запрос не может быть выполнен *точно*, API не выходит из строя — он переходит на ближайшее допустимое значение и добавляет короткий код в массив errornotes (например, Y01 = использован ближайший год, S05 = тень недоступна). Полный список находится в /api/errornotes.

Доставка и кэширование изображений

Возвращаемый image_url указывает на CDN, несет подпись плюс срок действия и заблокирован на точный трансформ — клиенты не могут его изменить. Первый запрос рендерит и кэширует байты; каждый последующий запрос подается прямо из кэша. Просто вставьте URL в <img src>.

Коды состояния

200 — успех. Всегда проверяйте errornotes на предмет молчаливых откатов.
401 — отсутствует или недействителен x-api-key.
403 — ваш план не позволяет запрашиваемую функцию, формат или бренд.
404 — нет данных по этому пути. Сообщение называет то, что нужно проверить.

Конвенции

Названия бренда/модели/варианта/комплектации не зависят от регистра и принимают распространённые синонимы.
Годы выпуска привязываются к ближайшей доступной генерации
Конечные точки каталога возвращают JSON; байты изображений поступают только из подписанного image_url