Como colocar uma imagem de carro com qualidade de estúdio em todos os anúncios do marketplace

Um site de classificados ou um catálogo de compra de carros vive ou morre pela sua grade. Cada card precisa de uma imagem no momento em que o anúncio é criado, e a foto do próprio vendedor chega depois, se chegar, num ângulo aleatório, numa garagem qualquer. A fotografia de banco de imagens tem o problema oposto: existe uma foto de imprensa licenciada para os carros populares nos anos populares, no ângulo e no fundo que a montadora escolheu, e para nada mais. Um catálogo que cobre de 1990 até o ano-modelo atual tem dezenas de milhares de lacunas.

O que as equipes que criam esses sites querem é entediante no melhor sentido: uma imagem de estúdio por ano-modelo, o mesmo ângulo e a mesma cor para todas, transparente para se encaixar em qualquer fundo do card, leve o bastante para ser servida dez mil vezes por dia.

Os catálogos construídos sobre a API hoje têm todos o mesmo formato, seja um site de classificados populando seus anúncios, um app de compra de carros renderizando seus cards de comparação ou um app móvel mostrando uma imagem principal por veículo:

• Uma carga inicial, depois um fluxo contínuo. Milhares de renderizações em poucas horas para cobrir o catálogo e, depois, algumas por dia, à medida que chegam novos anos-modelo e solicitações.
• Um ângulo, uma pintura ou uma paleta curta. A maioria escolhe front-3-4 ou side em prata ou branco. Um catálogo de compras que permite ao usuário escolher a cor renderiza algumas cores predefinidas por veículo; cada uma é mais uma imagem de veículo, não um novo pipeline.
• WebP em uma caixa fixa. De 512 a 1024 pixels de largura, entregue exatamente na caixa que o card usa, para que o front-end nunca precise cortar a imagem nem adicionar faixas.
• Armazenadas pelo ID do veículo. As renderizações vão para o armazenamento de objetos ou a CDN da própria equipe, ou as páginas carregam URLs assinadas; de qualquer forma, a chave é o ID estável veh_… do catálogo, não uma string de marca-modelo-ano.

O restante desta página é esse pipeline, passo a passo, com o código. Ele pressupõe uma chave de API com o escopo images:read e um plano dimensionado para o catálogo (veja as perguntas frequentes).

A falha mais comum na construção de um catálogo não é a renderização, é a grafia. Uma construção que gera strings de marca e modelo a partir de outro banco de dados pode gastar a maior parte das requisições com 404 vehicle_not_found: gratuito, mas uma ida e volta desperdiçada a cada vez, e uma grade cheia de buracos. A solução é deixar o catálogo dizer o que existe. GET /api/v1/vehicles é gratuito, não exige chave, e cada modelo retornado traz um ID de veículo estável (veh_ mais 13 caracteres) que nunca muda entre deploys ou versões do catálogo. Armazene esse ID no anúncio e renderize por ele.

?make=porsche&model=911 lista todos os anos de um modelo com um id por ano, e ?q= faz uma busca por texto livre quando um vendedor digita um nome. O mesmo catálogo é publicado como o pacote aberto @meterapp/vehicle-db, para que menus suspensos e validações possam rodar offline com a mesma lista. De qualquer forma, ao fim desta etapa você tem uma lista de ids, e nenhuma etapa seguinte precisa escrever o nome de um carro de novo.

Anúncios que já nomeiam seus carros com a grafia de outro banco de dados são mapeados em uma só chamada: POST /api/v1/vehicles/check lê até 2.000 deles do mesmo jeito que uma renderização leria e responde a cada um com o id de veículo, os veículos reais mais próximos quando o catálogo não tem esse carro, ou uma ausência a ser ignorada em todas as vistas e cores. car-image check listings.csv --out checked.csv grava os ids de volta no arquivo. É gratuito e evita descobrir as lacunas um 404 por vez.

Defina o card uma vez e codifique-o na query string. Tudo o que vem depois de vehicle= abaixo é uma decisão de enquadramento que você toma uma única vez para todo o catálogo:

• w=800&h=600&fit=contain entrega exatamente 800×600 com o carro inteiro visível e preenchimento transparente ao redor, para que todo card tenha a mesma tela. Já fit=cover preenche a caixa e recorta pelo centro.
• trim=1&padding=8 recorta no contorno do carro antes de ajustar, com 8% do lado maior como margem, para que um Suburban e um Miata preencham a caixa da mesma forma, em vez de flutuarem no quadro original.
• color=silver é o padrão e o neutro mais seguro; qualquer uma das 15 predefinições ou qualquer hex conta da mesma forma: uma imagem de veículo.
• format=webp é a menor codificação com canal alfa sem perdas. Quando um navegador carrega a URL diretamente (URLs assinadas, passo 4), format=auto negocia WebP ou PNG para cada cliente.

A resposta traz ETag, X-Image-Source (cache ou generated) e X-Vehicle-Id, o veículo do catálogo que foi entregue. Guarde o ETag junto com o arquivo: uma requisição posterior com If-None-Match responde 304 e não custa nada, e é assim que uma ressincronização noturna continua gratuita.

Três limites determinam uma carga inicial, e cada um deles se anuncia nos cabeçalhos em vez de falhar silenciosamente:

• Requisições por minuto. 120 por chave nos planos Free e Pro, 600 no Business, 1.200 no Enterprise, além de um limite por conta somando todas as chaves. Toda resposta autenticada traz RateLimit-Remaining; um 429 traz Retry-After. De quatro a oito requisições simultâneas é mais do que suficiente.
• Novas vistas de veículo. A primeira requisição de uma vista de veículo que ainda não preparamos leva um pouco de tempo enquanto a preparamos para que possa ser exibida em qualquer cor; todas as requisições seguintes, em qualquer cor, são servidas do cache. Preparar novas vistas consome a parcela da conta no orçamento diário de renderização (2% no Free, 10% no Pro, 25% no Business, 50% no Enterprise). Passado esse limite, um novo render responde 429 com code: account_generation_cap e reset_at (meia-noite UTC), nada é cobrado e as imagens em cache continuam sendo servidas. Uma grande carga retroativa leva algumas noites, não uma só.
• Imagens de veículo por mês. O Free inclui 100, o Pro 2.500 e o Business 10.000; o Enterprise é negociado. Acima dessa franquia, uma solicitação de imagem ainda não contabilizada neste mês responde 402 (plan_image_limit) e não conta nada; uma imagem já contabilizada neste mês é sempre servida, então uma grade em produção nunca quebra.

Falhas de renderização (502) devolvem sua imagem de veículo automaticamente, requisições simultâneas para a mesma variante nova compartilham uma única renderização, e um GET simples pode ser repetido com segurança. O SDK repete 429 e 503 por você, respeitando o Retry-After, e nunca repete um 402.

Há duas boas maneiras de colocar a imagem diante do comprador, e as implementações de catálogo usam as duas:

• Armazene os bytes. Grave cada renderização no seu próprio armazenamento de objetos ou CDN com o ID do veículo e sirva-a como qualquer outro arquivo estático. Essa é a resposta certa para uma grade exibida milhões de vezes: nenhuma chamada para nós a cada carregamento, e a licença de um plano pago cobre as cópias que você mantém para servir o seu produto.
• Gere URLs assinadas. POST /api/v1/image-urls aceita até cinquenta imagens por chamada, conta a imagem de cada URL como uma imagem de veículo do mês quando ela é gerada e retorna URLs sem chave que o navegador carrega diretamente. Defina ttl_seconds em até sete dias; adicione renew: true para páginas de anúncios que ficam no ar por mais tempo que isso (uma renovação conta a imagem uma vez no mês em que ocorre, e nada mais se ela já tiver sido contada naquele mês). Restrinja a chave às origens do seu site no painel, e uma URL copiada para outro lugar responde 403.

Envie um cabeçalho Idempotency-Key por página de anúncios ao gerar em lotes: uma chamada repetida com a mesma chave e o mesmo corpo reproduz a primeira resposta e não conta nada de novo.

Pesquise primeiro: GET /api/v1/vehicles?q= encontra um modelo por nome, prefixo ou correspondência aproximada, e POST /api/v1/images/resolve transforma uma frase em texto livre em parâmetros exatos, com um nível de confiança que orienta a decisão. O que ainda faltar depois disso vai para o quadro de solicitações: POST /api/v1/requests cria a solicitação ou, quando já existe uma aberta para a mesma marca, modelo e ano, registra um voto nela em vez de duplicá-la. O próprio catálogo é open source, e as adições chegam a todos os clientes.

Todo o pipeline roda pela CLI, sem nenhum código, e foi assim que mais de um catálogo na API foi populado:

• SDK: client.vehicles({ year, makeId }) para listar, client.getImage({ vehicle, … }) para renderizar, client.createImageUrls(…) para lotes de URLs assinadas. Consulte a documentação de imagens para ver todos os parâmetros.
• MCP: um assistente conectado a https://carimage.dev/api/mcp tem o mesmo catálogo (search_vehicles, resolve_vehicle) e as mesmas renderizações (get_car_image, create_car_image_urls), o que é a ferramenta certa para um curador que adiciona um veículo manualmente, e a errada para um preenchimento retroativo de milhares: use a CLI ou o SDK para isso e deixe o assistente para os casos restantes. A configuração está na página do MCP.