Começar

API Vehicle Imagery v1.2.0

Imagens de carro de qualidade de estúdio para todas as marcas, modelos, anos, variantes, acabamentos e vistas — entregues como URLs de CDN assinadas com formato, tamanho, proporção, cor da pintura, sombra, transparência, solo e espelhamento no chão, sob demanda

URL base

Todos os endpoints estão vivos sob https://api.vehicleimagery.com

Autenticação

Cada solicitação precisa da sua chave de API no cabeçalho x-api-key.

curl -H "x-api-key: YOUR_API_KEY" https://api.vehicleimagery.com/api/brands

O que sua chave pode fazer (formatos, proporções, funcionalidades, marcas) é retornado por /api/me. Os endpoints de documentação (/api/openapi.json, /api/docs) são públicos e não precisam de chave.

Como funciona

Navegue pelo catálogo até um carro: brand → model → year → variant → trim → view, por exemplo, GET /api/Abarth/124_Spider_Abarth/2016/Basis/base.
Resolva uma imagem adicionando a visão + opções: GET /api/Abarth/124_Spider_Abarth/2016/Basis/base/front_left?format=webp&width=1200 → retorna metadados mais uma image_url assinada.
Incorpore image_url diretamente na sua <img>. Ela é assinada e travada para transformação; os bytes são gerados na primeira solicitação e armazenados em cache no CDN pelo TTL do seu plano (padrão 7 dias).

Adicional da API v2: conjuntos de estúdio, giros de 360° e lifestyle (novo)

Chaves com o add-on API v2 também recebem nossos novos conjuntos de imagens de estúdio — no mesmo catálogo e com as mesmas chamadas. Verifique access em /api/me: v1 = imagens padrão, v2 = add-on, all = ambos. No endpoint de trim, um carro com imagens de add-on lista groups ao lado de views.

Vistas padrão (front, front_left … right) — mesmas URLs de sempre.
Grupos de estúdio — …/{trim}/{group} lista as imagens, …/{trim}/{group}/{image} resolve uma.
hero: fotos principais, vistas em três quartos, algumas do nível do chão (8 imagens)
steered: rodas dianteiras viradas, de três alturas de câmera (8 imagens)
extra: mais ângulos: todos os lados e cantos ao nível dos olhos, alto e baixo, cantos também a 30° e 45° (56 imagens)
drone: de cima: ângulos inclinados, vistas íngremes e diretamente de cima (7 imagens)
Os nomes das imagens indicam onde está a câmera: o lado (front, front_left, left, rear_right …) mais _eye (nível dos olhos), _high (acima), _low (baixo), _ground (no nível do chão), _30 / _45 (vista do canto a 30° / 45°), _steep (inclinado de cima) ou top (de cima para baixo). O número de imagens por carro pode variar; /api/getall e o endpoint de grupo mostram isso.
Girações de 360° — …/{trim}/360 lista os anéis (eye_level, low, high), …/{trim}/360/{ring} retorna cada frame com seu próprio image_url (uma rotação precisa de todos eles, em ordem).
Cenas de estilo de vida: …/{trim}/lifestyle lista as cenas, …/lifestyle/{scene} suas imagens, …/lifestyle/{scene}/{image} resolve uma.

Todo endpoint de referência conhece o add-on: /api/search e /api/getall incluem carros add-on (getall com seus groups), as /colors, /features e /all de um carro descrevem suas opções add-on, e /api/options, /api/sizes, /api/views e /api/me adicionam uma seção addon. Tudo também funciona por id estável (/api/id/{id}/…).

Imagens adicionais aceitam opções extras: lights, background (branco, transparente ou qualquer hex), color como hex (por exemplo, c8102e), windows=dark, plate (blank ou seu logo), fit, size e hotspots — veja *Resolver uma URL de imagem assinada*. Sem o add-on, esses parâmetros são ignorados e nenhum grupo é listado.

Nomes & ids: todos os carros, padrão e adicionais, usam a mesma nomenclatura do catálogo (por exemplo, Mercedes-Benz / C-Class, BMW / 5 series). Nomes usados antes de 5 de outubro de 2026 (por exemplo, Mercedes / C-Klasse) ainda resolvem e respondem com o nome atual. Nomes nunca contêm uma barra: onde o catálogo escreve uma, o nome tem um hífen (por exemplo, Chevrolet / C-K). Carros que existem apenas no adicional têm ids a partir de 900000000; /api/id/{id}/… funciona para eles como para qualquer outro carro.

Tem um veículo real? (Beta)

Se souber o VIN ou o número de registro do carro em vez de sua posição no catálogo, os add-ons de busca fazem os dois passos em uma chamada: GET /vin/{vin} e GET /plate/{plate} decodificam o veículo e retornam a correspondência mais próxima do catálogo com URLs de imagens assinadas ao lado dos dados decodificados. Ambos são opt-in por chave — verifique features.vin e features.plate em /api/me. Sem o add-on, eles retornam 403.

Opções de imagem

Adicione a qualquer solicitação de imagem: format, resolution, ratio, width, height, quality, color, shadow, transparency, ground, mirroring. Todas as opções combinam livremente (por exemplo, ?color=wine_red&shadow=true&format=webp&width=1200). O conjunto completo filtrado pelo plano está em /api/options.

Cores de pintura

Os carros podem ser repintados sob demanda: os reflexos, o cromo, o vidro e o interior permanecem intocados; apenas a pintura muda, fiel ao seu acabamento (sólido ou metálico). /api/colors lista todo o catálogo como pares { color_name, color_make }: as cores da casa (black, white, blue, orange, wine_red — color_make: "Vehicleimagery") estão disponíveis em todos os carros; as cores das marcas (por exemplo, Kia *Racing Red*) pertencem aos carros dessa marca. O endpoint /colors de um carro lista o que é mostrado para ele (cores da casa + as cores da marca do carro) — qualquer cor ativa do catálogo ainda pode ser solicitada em qualquer carro via ?color=. Detalhes: o guia *Cores de pintura* em /info/guides/colors.

Sombras, transparência e composição

Sombras do chão do estúdio (shadow=true), recortes transparentes (transparency=true) e entrega opaca branca são produzidos no momento da entrega para cada vista externa. A disponibilidade é uniforme em todo o catálogo.

Notas de erro (não fatais)

Quando um pedido não pode ser atendido exatamente, a API não falha. Ela recorre ao valor válido mais próximo e adiciona um código curto ao array errornotes (por exemplo, Y01 = ano mais próximo usado, S05 = sombra indisponível). A lista completa está em /api/errornotes.

Entrega e cache de imagens

O image_url retornado aponta para o CDN, carrega uma assinatura e uma data de expiração, e está bloqueado para a transformação exata — os clientes não podem alterá-lo. A primeira solicitação produz e armazena em cache os bytes; toda solicitação posterior é servida diretamente do cache. Basta inserir a URL em um <img src>.

Novas imagens são produzidas em uma fila justa: planos com prioridade mais alta vão primeiro, e solicitações idênticas que chegam ao mesmo tempo são produzidas uma vez. A primeira carga de uma nova combinação geralmente leva alguns segundos; o cabeçalho de resposta X-Cache informa de onde veio (MISS = acabou de ser produzida, HIT / HIT-R2 = cache, ORIGINAL = arquivo de origem sem alterações), X-Queue-Wait-Ms indica quanto tempo esperou. Se um número muito grande de novas imagens está sendo produzido ao mesmo tempo, uma URL de imagem pode responder 503 busy com Retry-After: 5 — basta carregá-la novamente alguns segundos depois.

Códigos de status

200 — success. Always check errornotes for silent fallbacks.
401 — missing or invalid x-api-key.
403 — your plan doesn't allow the requested feature, format or brand.
404 — no data for that path. The message names exactly what to check.
503 — (apenas URLs de imagens) muitas novas imagens estão sendo produzidas agora; tente novamente após os segundos em Retry-After.

Convenções

Os nomes de marca, modelo, variante e acabamento são insensíveis a maiúsculas e minúsculas e aceitam apelidos comuns.
Anos se ajustam à geração disponível mais próxima
Os endpoints do catálogo retornam JSON; os bytes da imagem vêm apenas do image_url assinado.