A imagem mostra a versão usada na cotação da mensalidade?

Não. O catálogo se baseia em marca, modelo e ano, então todas as versões de um ano-modelo são renderizadas como o mesmo veículo. Coloque a versão no texto da oferta, ao lado da imagem, e nunca descreva a imagem como sendo dessa versão ou como um carro em estoque.

Uma cor original da montadora custa mais do que uma cor predefinida?

Não. Cada pintura é uma recoloração de um único render neutro, então um hex custa 1 crédito, como qualquer uma das 15 predefinições, e um hex igual à amostra de uma predefinição é essa predefinição. O hex é aplicado exatamente com esse valor sRGB sob iluminação de estúdio; por isso, compare o render com a amostra de cor antes de a oferta entrar no ar.

Quanto custa um configurador com 4 cores de pintura?

400 créditos, uma única vez: 100 créditos por cada pintura do veículo. Pedir novamente um veículo e uma pintura que sua conta já possui é gratuito (billing.already_owned é true), e publicar, consultar o status, baixar e cada carregamento de um modelo publicado também são gratuitos.

Quanto tempo leva um modelo 3D e o que acontece se ele falhar?

O primeiro modelo de um veículo leva 10–20 minutes; cada pintura adicional do mesmo veículo reaproveita a malha e leva 1–2 minutes. Um modelo que falha é reembolsado integralmente e, quando a geração 3D atinge a capacidade diária, a solicitação é recusada com um horário para nova tentativa, antes de qualquer cobrança.

Um PDF de cotação pode manter a imagem depois que a oferta terminar?

Sim. Em um plano pago, a licença cobre uma renderização dentro do que o seu produto gera para os clientes, incluindo cotações e folhetos. Uma renderização entregue pelo plano mantém essa licença depois que o plano termina, então uma cotação armazenada nunca precisa perder a imagem. Para gerar a renderização de uma nova oferta, é preciso ter um plano ativo no momento.

Imagens de carros para cotações e ofertas de leasing

Um guia de implementação escrito com base no comportamento documentado da API; não cita nenhum cliente. Publicado em 30 de setembro de 2026.

O problema: a oferta é exata, a imagem não

Uma oferta de leasing é específica: um ano-modelo, a versão sobre a qual a parcela é cotada, uma pintura da paleta atual da fabricante, um valor mensal válido até uma data. A imagem ao lado dela muitas vezes não é: a foto de imprensa do ano passado, uma cor em que o carro não é mais oferecido, uma carroceria diferente. Quando a parcela é exata e a imagem é aproximada, é a imagem que o cliente questiona.

A mesma oferta então circula: vai para a página de um modelo, para o PDF de uma cotação, para um e-mail e para um configurador onde o cliente gira o carro. Cada um desses lugares precisa do mesmo veículo na mesma pintura.

Como fica a integração

Uma oferta por ano-modelo, identificada pelo id de veículo do catálogo daquele ano.
A cor de fábrica em hex, em todas as imagens da oferta.
A mesma imagem no PDF da cotação e no e-mail, por meio de URLs assinadas, para que nenhum documento ou renderizador precise guardar uma chave.
Um modelo 3D por cor para o configurador, publicado como um embed de duas linhas.

Etapa 1: vincule cada oferta ao id de veículo do ano-modelo correspondente

GET /api/v1/vehicles?make=&model= é gratuito e público e lista todos os anos de um modelo, cada um com seu id estável de veículo. Armazene junto com a oferta o id do ano-modelo correspondente.

Todos os anos de um modelo

curl -s "https://carimage.dev/api/v1/vehicles?make=honda&model=cr-v"

200 OK (resumido)

{
  "data": {
    "make": {
      "id": 474,
      "name": "HONDA",
      "slug": "honda"
    },
    "model": {
      "name": "CR-V",
      "slug": "cr-v",
      "vehicle_type": "Passenger Car"
    },
    "vehicles": [
      "…",
      {
        "year": 2025,
        "id": "veh_exjyt8r21gmhe"
      },
      {
        "year": 2026,
        "id": "veh_b6kgpb03d73r9"
      },
      {
        "year": 2027,
        "id": "veh_8nr7res56a6jq"
      }
    ]
  }
}

Quando as ofertas de 2027 entram no ar, elas recebem o id de 2027, e as ofertas de 2026 mantêm o seu: um id nunca muda, então uma página ou cotação criada com base nele continua funcionando após a virada do ano-modelo. O catálogo é indexado por marca, modelo e ano; portanto, a versão sobre a qual a parcela é cotada (um EX-L, um Sport Touring) é texto na oferta, nunca algo que a imagem afirma.

Passo 2: a pintura do fabricante, por hex

As 15 predefinições cobrem as cores comuns; uma oferta pede a pintura em que o carro é realmente oferecido. Pegue o hex da amostra de cor do fabricante e envie-o sem prefixo em uma URL (color=1f3a5f) ou com o # em JSON ("color": "#1f3a5f"). Um hex custa os mesmos 1 crédito que uma predefinição, porque toda pintura é uma recoloração de um único render neutro, e um hex igual à amostra de uma predefinição é essa predefinição, armazenada em cache uma só vez.

A imagem da oferta

# the 2026 offer's hero: its model year, in the paint it is offered in, cropped to a 16:9 slot
curl --fail-with-body -H "Authorization: Bearer $CAR_IMAGE_API_KEY" \
  "https://carimage.dev/api/v1/images/car?vehicle=veh_b6kgpb03d73r9&view=front-3-4&color=1f3a5f&w=1024&h=576&fit=contain&trim=1&padding=4&format=webp" \
  -o cr-v-2026-offer.webp

Compare a renderização com a amostra de cor

Um hex é aplicado exatamente com esse valor sRGB sob iluminação de estúdio, e as renderizações ainda podem errar uma cor ou um detalhe (consulte precisão das imagens). Confira a renderização antes de a oferta entrar no ar e informe qualquer uma que esteja incorreta pelo card Imagens recentes do painel.

Passo 3: o PDF da cotação e o e-mail da oferta, por meio de URLs assinadas

Um PDF de cotação geralmente é HTML renderizado por um serviço de PDF ou por um navegador headless. Coloque no template uma URL assinada de POST /api/v1/image-urls, nunca a chave: o renderizador carrega a imagem uma vez e a incorpora, então a validade padrão de 1 hora é mais que suficiente, e format: "jpg" a aplica sobre fundo branco, o que combina com um documento. A URL custa 1 crédito quando é gerada.

O e-mail da oferta é aberto sempre que o cliente chega até ele. Gere a imagem dele com renew: true e ttl_seconds no máximo de 7 dias, e defina renew_days como os dias restantes da oferta: cada semana adicional em que o e-mail é aberto custa 1 crédito, semanas sem aberturas não custam nada e, quando a oferta termina, a URL deixa de ser renovada e expira. Em um plano pago, a licença cobre uma renderização dentro do que seu produto gera para os clientes, inclusive uma proposta.

O PDF e o e-mail, com o SDK TypeScript

import { CarImageClient, type ImageParams } from "@meterapp/car-image-sdk";

const client = new CarImageClient({ apiKey: process.env.CAR_IMAGE_API_KEY });

// The offer's picture: its model year, in the paint it is offered in.
const offerImage: ImageParams = {
  vehicle: offer.vehicleId, view: "front-3-4", color: offer.paintHex, // "#1f3a5f"
  width: 1024, height: 576, fit: "contain", trim: true, padding: 4,
};

// The quote PDF: rendered from HTML, the picture loaded once and embedded, on white.
const { data: [forPdf] } = await client.createImageUrls({ ...offerImage, format: "jpg" });
const pdf = await renderQuotePdf({ ...quote, vehicleImageUrl: forPdf.url });

// The offer email: loads for as long as the offer runs, then stops renewing.
const { data: [forEmail] } = await client.createImageUrls(
  { ...offerImage, width: 600, height: 338, format: "auto" },
  {
    ttlSeconds: 604800,
    renew: true,
    renewDays: Math.min(Math.max(daysUntil(offer.endsOn), 1), 365),
    idempotencyKey: `offer:${offer.id}:email`,
  }
);

Etapa 4: um modelo 3D para o configurador

POST /api/v1/3d com o id do veículo da oferta, sua pintura e publish: true gera um modelo texturizado (GLB, USDZ, FBX e uma versão para navegador) e fornece URLs sem chave com um código de incorporação de duas linhas. Custa 100 créditos (US$ 1,00) por veículo e cor, cobrado uma única vez; pedir de novo o mesmo veículo na mesma pintura pela sua conta é gratuito. O primeiro modelo de um veículo leva 10–20 minutes, e cada pintura adicional reutiliza a malha e leva 1–2 minutes.

Uma cor do configurador

curl --fail-with-body -X POST https://carimage.dev/api/v1/3d \
  -H "Authorization: Bearer $CAR_IMAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: configurator-cr-v-2026-1f3a5f" \
  -d '{"vehicle": "veh_b6kgpb03d73r9", "color": "#1f3a5f", "publish": true}'

202 Accepted (resumido)

{
  "data": {
    "id": "5b0f3c2e-8a41-4d7e-9c10-2f6e1a3b4d58",
    "object": "3d_model",
    "status": "queued",
    "progress": 0,
    "vehicle": {
      "id": "veh_b6kgpb03d73r9",
      "make": "honda",
      "model": "cr-v",
      "year": 2026
    },
    "color": "#1f3a5f",
    "files": null,
    "public": {
      "id": "m3d_…",
      "url": "https://carimage.dev/api/v1/3d/public/m3d_…",
      "files": null,
      "embed": {
        "script": "https://carimage.dev/embed/3d.js",
        "html": "<script src=\"https://carimage.dev/embed/3d.js\" async></script>\n<car-3d model=\"m3d_…\"></car-3d>"
      }
    }
  },
  "billing": {
    "charged_on": "creation",
    "credits_charged": 100,
    "already_owned": false
  }
}

Consulte GET /api/v1/3d/{id} periodicamente (a cada 10–15 segundos é suficiente) ou passe um webhook_url com um webhook_secret e receba um único POST assinado quando o modelo estiver pronto. data.public.embed.html contém o script e um elemento <car-3d>: cole-o na página da oferta. O elemento mostra o pôster na hora e carrega o visualizador na primeira vez que o modelo aparece na tela durante a rolagem; view, spin, backdrop, ar e alt definem o ângulo inicial, a rotação 360°, o fundo, um botão de RA nos celulares (Quick Look via USDZ no iOS) e o texto alternativo. A publicação e todos os carregamentos são gratuitos.

Um seletor de cores para os modelos publicados

<script src="https://carimage.dev/embed/3d.js" async></script>

<select id="paint" aria-label="Paint">
  <option value="1f3a5f">Blue</option>
  <option value="white">White</option>
</select>

<!-- One published model per paint. Only the visible one is loaded: the script
     fetches a viewer the first time a model scrolls into view. -->
<car-3d data-paint="1f3a5f" model="m3d_…" view="front-3-4" spin backdrop="studio" ar
        alt="2026 Honda CR-V in the offer's blue"></car-3d>
<car-3d data-paint="white" model="m3d_…" view="front-3-4" spin backdrop="studio" ar
        alt="2026 Honda CR-V in white" hidden></car-3d>

<script>
  document.querySelector("#paint").addEventListener("change", (event) => {
    for (const model of document.querySelectorAll("car-3d[data-paint]")) {
      model.hidden = model.dataset.paint !== event.target.value;
    }
  });
</script>

Um configurador com 4 cores são 4 modelos, 400 créditos uma única vez. As oficinas de envelopamento e insulfilm que usam a API encomendam modelos 3D da mesma forma; a história delas aborda os arquivos e os formatos, e a documentação de 3D aborda webhooks, downloads e cancelamento de publicação.

CLI, SDK e MCP

CLI: npx @meterapp/car-image 3d create --vehicle veh_b6kgpb03d73r9 --color "#1f3a5f" --publish --wait solicita uma cor de pintura, aguarda a conclusão e imprime o código de incorporação.
SDK: client.vehicles({ make, model }), client.createImageUrls(…), client.create3dModel({ vehicle }, { color, publish: true }) e client.wait3dModel(id).
MCP: com ?toolset=all, create_3d_model, get_3d_model e publish_3d_model permitem que um assistente encomende e publique uma pintura para um vendedor. A configuração está na página do MCP.

Perguntas frequentes

A imagem mostra a versão usada na cotação da mensalidade?: Não. O catálogo se baseia em marca, modelo e ano, então todas as versões de um ano-modelo são renderizadas como o mesmo veículo. Coloque a versão no texto da oferta, ao lado da imagem, e nunca descreva a imagem como sendo dessa versão ou como um carro em estoque.
Uma cor original da montadora custa mais do que uma cor predefinida?: Não. Cada pintura é uma recoloração de um único render neutro, então um hex custa 1 crédito, como qualquer uma das 15 predefinições, e um hex igual à amostra de uma predefinição é essa predefinição. O hex é aplicado exatamente com esse valor sRGB sob iluminação de estúdio; por isso, compare o render com a amostra de cor antes de a oferta entrar no ar.
Quanto custa um configurador com 4 cores de pintura?: 400 créditos, uma única vez: 100 créditos por cada pintura do veículo. Pedir novamente um veículo e uma pintura que sua conta já possui é gratuito (billing.already_owned é true), e publicar, consultar o status, baixar e cada carregamento de um modelo publicado também são gratuitos.
Quanto tempo leva um modelo 3D e o que acontece se ele falhar?: O primeiro modelo de um veículo leva 10–20 minutes; cada pintura adicional do mesmo veículo reaproveita a malha e leva 1–2 minutes. Um modelo que falha é reembolsado integralmente e, quando a geração 3D atinge a capacidade diária, a solicitação é recusada com um horário para nova tentativa, antes de qualquer cobrança.
Um PDF de cotação pode manter a imagem depois que a oferta terminar?: Sim. Em um plano pago, a licença cobre uma renderização dentro do que o seu produto gera para os clientes, incluindo cotações e folhetos. Uma renderização entregue pelo plano mantém essa licença depois que o plano termina, então uma cotação armazenada nunca precisa perder a imagem. Para gerar a renderização de uma nova oferta, é preciso ter um plano ativo no momento.

Continue lendo

História de cliente · Aftermarket automotivoComo visualizar um envelopamento, película ou PPF no carro exato do clienteO cliente quer ver o envelopamento no carro dele, não no de outra pessoa. As oficinas renderizam o ano-modelo exato em branco, aplicam o material por cima, reproduzem uma pintura por hex e pedem um modelo 3D para a visualização giratória.