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) общедоступны и не требуют ключа.

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

1. Перемещайтесь по каталогу до одного автомобиля: brand → model → year → variant → trim → view, например, GET /api/Abarth/124_Spider_Abarth/2016/Basis/base.
2. Разрешите изображение, добавив вид + опции: GET /api/Abarth/124_Spider_Abarth/2016/Basis/base/front_left?format=webp&width=1200 → возвращает метаданные и подписанный image_url
3. Вставьте image_url прямо в ваш <img>. Он подписан и защищен от изменений; байты генерируются при первом запросе и кэшируются на CDN по TTL вашего плана (по умолчанию 7 дней).

Дополнение 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 — передние колеса повернуты, с трех высот камеры (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 (белый, прозрачный или любой hex), color в виде hex (например, c8102e), windows=dark, plate (blank или ваш logo), fit, size и hotspots — см. *Разрешение URL подписанного изображения*. Без дополнения эти параметры игнорируются и группы не отображаются.

Названия и идентификаторы: все автомобили, стандартные и дополнительные, используют одинаковое каталоговое наименование (например, Mercedes-Benz / C-Class, BMW / 5 series). Названия, использованные до 5 октября 2026 года (например, Mercedes / C-Klasse), по-прежнему разрешаются и отвечают текущим именем. Названия никогда не содержат слэш: где каталог пишет один, имя имеет дефис (например, Chevrolet / C-K). Автомобили, которые существуют только в дополнении, имеют идентификаторы от 900000000; /api/id/{id}/… работает для них так же, как и для любого другого автомобиля.

У вас есть реальный автомобиль? *(Beta)*

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