Car Image API

Toepassingen · Verzekeringen

Autoafbeeldingen voor schadeclaims en verzekeringsoffertes

Decodeer gratis het VIN op een polis of schadeclaim, bewaar het voertuig-id en toon één gelabelde weergave van het verzekerde model in het schadedossier en de offerte-pdf.

Een implementatiegids op basis van het gedocumenteerde gedrag van de API; er wordt geen klant genoemd. Gepubliceerd op .

Het probleem: het dossier noemt een auto die niemand kan zien

Een offerteformulier, een polisregistratie en een eerste schademelding noemen het voertuig allemaal op dezelfde manier: met het VIN, getypt door een klant of overgenomen van een kentekenbewijs. Alles wat iemand daarna over de auto ziet, is tekst: een bouwjaar, een merk, een model en misschien een uitvoering. Wie naast een regel tekst vraagt "Is dit uw voertuig?", krijgt op alles een ja.

Met een afbeelding van het model waarnaar de VIN decodeert, kunnen de klant en de schade-expert in één oogopslag controleren of het dossier het juiste soort auto noemt. Welke auto het is, kan de afbeelding niet laten zien: een render is een studio-illustratie van een merk, model en bouwjaar uit de catalogus, en stelt geen specifiek fysiek voertuig voor. Dat ene feit bepaalt de hele integratie hieronder.

Hoe de integratie eruitziet

  • Decodeer bij intake. De offerteflow of het polissysteem decodeert het VIN één keer, gratis, en slaat de voertuig-id uit de catalogus op bij de polis. Schadeclaims die op de polis worden geopend, nemen die over.
  • Overal één aanzicht. front-3-4, de hero-hoek, in één kader op het offertescherm, de schadebehandelingsomgeving, de offerte-pdf en het polisportaal, zodat elk scherm het model op dezelfde manier toont.
  • Ondertekende URL's, nooit de sleutel. Browsers en PDF-renderers laden URL's zonder sleutel die uw server aanmaakt.
  • Woorden voor wat een afbeelding niet kan zeggen. Uitvoering, opties, de geregistreerde kleur, schade en kilometerstand blijven tekst en foto's, en bij de afbeelding staat dat deze representatief is.

Stap 1: de VIN decoderen, gratis

GET /api/v1/vin/{vin} is gratis en vereist een sleutel met images:read. Het antwoord bevat de gedecodeerde velden uit de vPIC-gegevens van NHTSA (bouwjaar, merk, model, uitvoering, serie, carrosserieklasse, motor en elk ander kenmerk dat vPIC kent) en, als de catalogus het voertuig bevat, een vehicle-object met de stabiele id en een kant-en-klaar image_path.

Decodeer het VIN op de offerte
curl --fail-with-body \
  -H "Authorization: Bearer $CAR_IMAGE_API_KEY" \
  "https://carimage.dev/api/v1/vin/WP0AA2A96RS201834"
200 OK (ingekort)
{
  "data": {
    "vin": "WP0AA2A96RS201834",
    "valid": true,
    "errors": [],
    "suggested_vin": null,
    "year": 2024,
    "make": "Porsche",
    "model": "911",
    "trim": "Carrera, Carrera T, Carrera 4",
    "series": "Type 992",
    "body_class": "Coupe",
    "vehicle": {
      "id": "veh_78qtwrgh37bkr",
      "make": "Porsche",
      "model": "911",
      "year": 2024,
      "image_path": "/api/v1/images/car?vehicle=veh_78qtwrgh37bkr"
    },
    "source": "vpic-db"
  }
}

Lees de trim: "Carrera, Carrera T, Carrera 4". Het patroon van dit VIN dekt drie uitvoeringen, dus zelfs het decoderen kan niet zeggen welke de polis verzekert, en een render van de 2024 911 al helemaal niet. Vraag de klant de uitvoering te bevestigen, bewaar deze samen met series en body_class als tekst en laat de afbeelding het model tonen.

  • Een VIN met een onjuist controlecijfer wordt toch gedecodeerd, met valid: false en het probleem in errors; suggested_vin markeert het teken dat volgens vPIC fout is met !, en dat toont u aan degene die het invoert.
  • Een formulier dat alleen de eerste tekens heeft, kan een gedeeltelijk VIN versturen: minstens vijf tekens, met * voor elke onbekende positie en een optioneel year.
  • Een 404 betekent dat vPIC het patroon niet kent. vPIC dekt voertuigen die voor de Amerikaanse markt zijn gemaakt, dus begin voor andere markten bij het merk en model met POST /api/v1/images/resolve, wat ook gratis is.

Stap 2: bewaar het voertuig-id bij de polis en de schadeclaim

Sla data.vehicle.id als gewone string op bij de polis en kopieer die naar elk schadedossier dat erop wordt geopend. De id is deterministisch en permanent: hetzelfde voertuig heeft dezelfde id bij elke deploy en na elke catalogusrelease, dus u kunt hem veilig als foreign key gebruiken, en elk volgend verzoek vermeldt vehicle=veh_78qtwrgh37bkr in plaats van een merk en model uit te schrijven.

Als data.vehicle null is, staan het gedecodeerde merk en model niet in de catalogus, zoals bij aanhangers en sommige bedrijfswagenchassis. U kunt de gedecodeerde velden nog steeds tonen. Toon ze zonder afbeelding en zet er nooit een vergelijkbare auto voor in de plaats.

Stap 3: één aanzicht in het schadedossier en de offerte-PDF

Het offertescherm, de schadebehandelingsomgeving en het polisportaal zijn browserapps, dus uw server maakt ondertekende URL’s aan met POST /api/v1/image-urls: elke URL telt zijn afbeelding als voertuigafbeelding van de maand op het moment dat hij wordt aangemaakt, tot 50 per aanroep, en is gratis te laden tot hij verloopt. Kader het beeld één keer en hergebruik die vorm: front-3-4 in een kader van 640×400 met fit: "contain", en trim met een beetje padding zodat een coupé en een pick-up het kader op dezelfde manier vullen. Hoe lang elke URL geldig moet blijven, hangt af van waar die wordt getoond:

  • De werkomgeving voor schadebehandeling. Maak de URL aan wanneer het scherm wordt opgebouwd. De standaardgeldigheidsduur van 1 uur dekt een werksessie, en een schadedossier dat morgen opnieuw wordt geopend, krijgt een nieuwe URL.
  • De offerte-pdf. Wanneer de pdf vanuit HTML wordt gegenereerd, laadt de renderer de afbeelding één keer en sluit die in, dus de standaardlevensduur is ruim voldoende en de pdf-service krijgt uw sleutel nooit in handen. format: "jpg" plaatst de afbeelding op een witte achtergrond, precies wat een document nodig heeft.
  • Het polisportaal en de verlengingsmail. Deze gaan langer mee dan welke levensduur ook, dus maak de URL aan met renew: true en ttl_seconds: 604800 (7 dagen). De URL blijft werken, een verlenging telt de afbeelding één keer mee in de maand waarin die valt, en niets extra als die die maand al was geteld, en renew_days: 365, het toegestane maximum, dekt een polistermijn van een jaar.

Geef de sleutel die de URL's aanmaakt een lijst met toegestane origins in het dashboard: een URL die vanaf een andere site wordt geladen, antwoordt met 403 en origin_not_allowed, terwijl e-mailclients en PDF-viewers, die geen Referer meesturen, hem nog steeds laden. Als u de sleutel intrekt, werken alle URL's die ermee zijn aangemaakt niet meer.

Intake, de werkbank, de pdf en het portaal, met de TypeScript SDK
import { CarImageClient, type ImageParams } from "@meterapp/car-image-sdk";

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

// Quote or policy intake: the VIN in, the vehicle id and the decoded words on the record. Free.
const { data: decoded } = await client.decodeVin(policy.vin);
policy.vehicleId = decoded.vehicle?.id ?? null; // null: show the decoded text and no picture
policy.trimText = decoded.trim;                 // "Carrera, Carrera T, Carrera 4": words, never the picture

if (policy.vehicleId) {
  // One view, framed once, for every screen and document that shows this policy's car.
  const view: ImageParams = {
    vehicle: policy.vehicleId, view: "front-3-4", color: policy.paintHex ?? "silver",
    width: 640, height: 400, fit: "contain", trim: true, padding: 6,
  };

  // The claims workbench: a URL for this session, minted when the screen draws.
  const { data: [workbench] } = await client.createImageUrls({ ...view, format: "auto" });

  // The quote PDF: the HTML-to-PDF renderer loads the URL once and embeds the picture.
  const { data: [pdf] } = await client.createImageUrls({ ...view, format: "jpg" });

  // The policy portal and the renewal email: one URL that keeps working for the term.
  const { data: [portal] } = await client.createImageUrls(
    { ...view, format: "auto" },
    { ttlSeconds: 604800, renew: true, renewDays: 365, idempotencyKey: `policy:${policy.id}:image` }
  );
}

Stap 4: label de afbeelding als het model, nooit als de verzekerde auto

Zet het label waar de afbeelding staat, niet alleen in een voetnoot: in de alt-tekst en in een bijschrift onder de afbeelding. De render toont het merk, model en bouwjaar in een lakkleur die u kiest, en color kan de kleur op de polis volgen (een presetnaam of een willekeurige hexwaarde). Het blijft het model in die kleur, niet de auto van de klant.

Het voertuigblok van een offerte
<figure>
  <img src="https://carimage.dev/api/v1/delivery/eyJhbGciOi…" width="640" height="400"
       alt="Representative image of a 2024 Porsche 911, not a photo of the insured vehicle">
  <figcaption>
    2024 Porsche 911 · Coupe · Type 992 · trim on the VIN: Carrera, Carrera T or Carrera 4
    <small>Representative image of the model. Not a photo of the insured vehicle.</small>
  </figcaption>
</figure>

Wat het kost en welk abonnement past

  • Gratis: de VIN-decodering, resolve, catalogusopvragingen en elke keer dat een signed URL binnen de geldigheidsduur wordt geladen.
  • Eén voertuigafbeelding: elk voertuig in elke lakkleur en elk aanzicht, één keer per maand geteld, hoe vaak het ook wordt geleverd, aangemaakt of verlengd, in elk formaat en elke bestandsindeling.
  • Voertuigafbeeldingen per maand: een offertefunnel ziet veel verschillende voertuigen, en elk plan bevat er een aantal per maand: Free 100, Pro 2.500 en Business 10.000; over Enterprise wordt onderhandeld. Een afbeelding die deze maand al is geteld, wordt altijd geleverd, en een verzoek boven het tegoed krijgt een 402 voordat er iets wordt geteld, dus kies het plan op basis van de voertuigen waarvoor u offertes maakt.

Met een betaald abonnement dekt de licentie een render in wat uw product voor zijn gebruikers maakt, een offerte of rapport inbegrepen, zolang het abonnement actief is; de details staan in de licentie.

CLI, SDK en MCP

npx @meterapp/car-image
# decode for free and keep the id
npx @meterapp/car-image vin WP0AA2A96RS201834 --json | jq -r .data.vehicle.id

# one renewing URL for the policy's documents, minted once however often intake retries
npx @meterapp/car-image url --vehicle veh_78qtwrgh37bkr --view front-3-4 --width 640 --height 400 \
  --fit contain --trim --padding 6 --format auto --ttl 604800 --renew --renew-days 365 \
  --idempotency-key policy-88213-image
  • SDK: client.decodeVin(vin, { year? }) en client.createImageUrls(…), zoals hierboven; client.resolve(query) voor een voertuig zonder VIN.
  • MCP: decode_vin en create_car_image_urls zitten in de kerntoolset, zodat een assistent met de schadeclaim in context aan de hand van het geregistreerde VIN kan antwoorden op "laat me het verzekerde model zien". De installatie staat op de MCP-pagina.

Veelgestelde vragen

Kan de afbeelding foto's van het verzekerde voertuig vervangen?
Nee. Het is een studiorender van het merk, model en bouwjaar uit de catalogus, geen foto, en er staat geen specifiek voertuig op. Het helpt een klant of schade-expert te zien dat het dossier de juiste soort auto noemt. Staat, schade, uitvoering, opties en aanpassingen blijken uit foto's, inspecties en de gedecodeerde tekst, en bij de afbeelding moet staan dat die representatief is.
Wat kost een afbeelding bij elke offerte?
Het decoderen van de VIN is gratis. De afbeelding telt als één voertuigafbeelding van de maand wanneer de ondertekende URL wordt aangemaakt of de bytes aan uw server worden geleverd, en wordt daarna zo vaak als nodig geleverd; een ondertekende URL laden is gratis tot hij verloopt. Een verlengende URL telt de afbeelding eenmaal in elke latere maand waarin hij wordt geopend, en niets in maanden waarin niemand kijkt.
De VIN wordt gedecodeerd, maar vehicle is null. Wat nu?
De decoder herkende het voertuig, maar de catalogus heeft geen vermelding voor dat merk, model en jaar. Dat gebeurt bij aanhangwagens en sommige bedrijfswagenchassis. Toon de gedecodeerde velden zonder afbeelding en vervang het voertuig nooit door een vergelijkbare auto. Zoek in de catalogus voor het geval de spelling afwijkt, en als het echt ontbreekt, vraag het dan aan op het openbare verzoekenbord.
Werkt VIN-decodering voor voertuigen van buiten de Amerikaanse markt?
De decoder gebruikt de vPIC-gegevens van NHTSA, die voertuigen voor de Amerikaanse markt omvatten. Een correct ingevoerd VIN van een andere markt kan daardoor 404 opleveren of zonder model worden gedecodeerd. Zoek die auto in dat geval op merk, model en bouwjaar met het gratis resolve-endpoint; de catalogus zelf omvat ook modelnamen van andere markten.
Hoe lang mag een schadedossier de afbeelding bewaren?
Zolang uw abonnement actief is. Met een betaald abonnement dekt de licentie een render in wat uw product produceert, een offerte of rapport inbegrepen; binnen 30 dagen na het einde van het abonnement worden opgeslagen kopieën verwijderd. Wilt u afbeeldingen voorgoed in dossiers bewaren, koop ze dan als Image Pack. Renders kunnen in de loop van de tijd ook worden verbeterd, dus een dossier dat precies moet vastleggen wat de klant zag, moet het bestand opslaan in plaats van een URL.

Lees verder

Klantverhaal · DealersoftwareZo maakt u in dealersoftware van een VIN of een voorraadlijst een foto voor elk voertuigEen voorraadrecord heeft een VIN en een voorraadnummer lang voordat het een foto heeft. Dealertools decoderen de VIN gratis, bewaren het voertuig-id in het record en tonen via signed URLs één consistente weergave in het CRM.