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.

Duas formas de entrada

Conhece o carro? Navegue pelo catálogo: marca → modelo → ano → variante → acabamento → vista. Tem um veículo real? Use os complementos de busca: GET /vin/{vin} ou GET /plate/{plate} transformam um VIN ou número de registro diretamente em dados do veículo *e* imagens de estúdio desse carro, com a cor real da pintura aplicada quando disponível. Os complementos são habilitados por chave; /api/me mostra o que a sua pode fazer.

Como funciona

1. Navegue pelo catálogo até um carro: brand → model → year → variant → trim → view, por exemplo, GET /api/Abarth/124_Spider_Abarth/2016/Basis/base.
2. 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.
3. 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).

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 mais uma data de expiração, e está bloqueado para a transformação exata — os clientes não podem alterá-lo. A primeira solicitação renderiza e armazena em cache os bytes; toda solicitação posterior é servida diretamente do cache. Basta inserir a URL em um <img src>.

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.

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.