Car Image API

Zákazníci · Nástroje pro dealery, dovoz a VIN

Jak v softwaru pro autobazary a dealery převést VIN nebo skladovou tabulku na fotografii každého vozidla

Jak se nástroje pro dealery a import dostanou od VIN nebo řádku skladového listu ke studiovému obrázku u každého záznamu: bezplatné dekódování VIN, resolve, stabilní ID a podepsané URL.

Průvodce: autosalony a VIN

Problém: záznam má VIN měsíce předtím, než má fotku

Skladový záznam v CRM, ERP nebo systému pro správu autosalonu (DMS) začíná jako VIN, skladové číslo a cena. Fotka přijde, až přijde fotograf, a u některých vozů nepřijde vůbec: vůz na cestě, vůz na protiúčet, který se ještě připravuje k prodeji, dovoz, jehož název modelu neodpovídá ničemu v obrazovém feedu DMS, auto z 90. let, k jehož tiskové fotce nikdo nekoupil licenci. Každá obrazovka, která tento záznam zobrazuje – seznam prodejce, ocenění výkupčího, nabídka pro zákazníka –, místo toho ukazuje šedý zástupný obrázek.

Nástroje pro dealery a import, které běží na API, vyplňují tento zástupný obrázek z toho, co už záznam obsahuje. Pokud má VIN, obrázek dělí jen jedno bezplatné dekódování. Pokud má jen řádek ve skladovém seznamu, dostane se k němu resolve z volného textu. Tak či tak záznam nakonec obsahuje stabilní ID vozidla a každá obrazovka zobrazí stejné auto stejným způsobem.

Jak vypadá integrace pro autosalony

  • Dekódujte při příjmu. VIN se dekóduje jednou, při vytvoření záznamu, a ID vozidla z katalogu se uloží vedle něj. Nic dalšího v procesu už nevypisuje značku ani model.
  • Jeden pohled pro seznam, jeden pro detail. Čistý side v širokém rámečku pro seznamy skladových vozů; front-3-4 pro stránku detailu a cenovou nabídku.
  • Starší ročníky. Dovozové a ojeté vozy sahají až do 90. let a renderují se stejně jako nové přírůstky: katalog pokrývá období od roku 1990 po aktuální modelový rok, včetně modelů pro japonský domácí trh.
  • Podepsané URL přímo v aplikaci. CRM běží v prohlížeči, takže načítá podepsané URL bez klíče vytvořené serverem, až padesát na jedno volání, a u záznamů, které existují déle než týden, je obnovuje.

Krok 1: dekódujte VIN, zdarma

GET /api/v1/vin/{vin} je zdarma a stačí k němu API klíč. Vrací dekódovaný rok, značku, model, výbavu, typ karoserie, motor a všechny další atributy, které obsahují data vPIC od NHTSA, a pokud vozidlo v katalogu je, také objekt vehicle se stabilním ID a připravenou cestou image_path. Fungují i částečné VIN: alespoň pět znaků, * za každou neznámou pozici a volitelně nápověda year.

Dekódování
curl -s -H "Authorization: Bearer $CAR_IMAGE_API_KEY" \
  "https://carimage.dev/api/v1/vin/1HGCM82633A004352"
200 OK (zkráceno)
{
  "data": {
    "vin": "1HGCM82633A004352",
    "valid": true,
    "year": 2003,
    "make": "Honda",
    "model": "Accord",
    "trim": "EX-V6",
    "body_class": "Coupe",
    "vehicle": {
      "id": "veh_3qfyk22gfhsx3",
      "make": "Honda",
      "model": "Accord",
      "year": 2003,
      "image_path": "/api/v1/images/car?vehicle=veh_3qfyk22gfhsx3"
    }
  },
  "request_id": "req_01j9x…"
}

Krok 1b: když máte jen řádek ve skladovém seznamu

Dovážené vozy často přicházejí jako tabulka: rok, značka, název modelu v jakémkoli zápisu, který použila aukční síň, a kód stupně nebo verze výbavy. POST /api/v1/images/resolve je zdarma a deterministický: vytáhne z fráze slova označující rok, barvu a pohled, se zbytkem prohledá katalog a vrátí přesné parametry s mírou jistoty, podle které se můžete rozhodnout.

Dohledání vozu z řádku skladové evidence
curl -s -X POST https://carimage.dev/api/v1/images/resolve \
  -H "Authorization: Bearer $CAR_IMAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "2019 toyota voxy zs side"}'
200 OK (zkráceno)
{
  "data": {
    "params": {
      "vehicle_id": "veh_9w0nvw7jphp6r",
      "make": "toyota",
      "model": "voxy",
      "year": 2019,
      "view": "side",
      "color": "silver"
    },
    "display": {
      "make_name": "TOYOTA",
      "model_name": "VOXY"
    },
    "confidence": "low",
    "image_path": "/api/v1/images/car?make=toyota&model=voxy&year=2019&view=side&color=silver"
  },
  "request_id": "req_01j9x…"
}

Vozidlo je správně (Toyota Voxy 2019), ale spolehlivost je low, protože „ZS“ je stupeň výbavy, který katalog nezná, a párování ho muselo obejít. Při hromadném importu berte high jako hotové a medium a low předložte člověku se seznamem candidates. Když tabulka už má rok a značku ve vlastních sloupcích, pošlete je v polích year a make a do query dejte jen model; párování bude mnohem čistší. Fráze bez slov označujících vozidlo vrací 400 a značka bez odpovídajícího modelu vrací 404 se seznamem ročníků dané značky, abyste se mohli zeptat na model.

Krok 2: uložte ID vozidla do záznamu

Ať jste se sem dostali jakoukoli cestou, uložte vehicle.id (nebo params.vehicle_id) do skladového záznamu jako obyčejný textový sloupec. ID je deterministické a trvalé: stejné vozidlo má stejné id při každém nasazení i po každém vydání katalogu, takže je bezpečné jako cizí klíč. Od té chvíle je každý požadavek na obrázek vehicle=veh_…, který nelze napsat špatně, a značka, kterou výrobce přejmenuje nebo zdroj zařadí jinak, nikdy nerozbije uložené URL.

Krok 3: jeden pohled pro seznam, jeden pro stránku detailu

Seznamy skladových vozů jsou široké a nízké, takže obvyklou volbou je přímý pohled z boku v rámečku 2:1: každý vůz směřuje stejným směrem a stojí na stejné základní linii. trim=1&padding=6 před umístěním ořízne obrázek na auto, takže Hilux i Yaris vyplní řádek stejně; fit=contain zachová plátno přesně 640×320 s průhlednými okraji. Stránka detailu používá front-3-4 v rozlišení 1024 a obě sdílejí mezipaměť: lak, který nezadáte, je na obou stříbrný.

Obrázek do seznamu pro jeden záznam
curl --fail-with-body -H "Authorization: Bearer $CAR_IMAGE_API_KEY" \
  "https://carimage.dev/api/v1/images/car?vehicle=veh_3qfyk22gfhsx3&view=side&w=640&h=320&fit=contain&trim=1&padding=6&format=webp" \
  -o stock-4471.webp

Krok 4: zobrazte ho v CRM přes podepsané URL

CRM běží v prohlížeči a prohlížeč nikdy nesmí mít API klíč. Když obrazovka zobrazuje stránku skladových vozů, server pomocí POST /api/v1/image-urls vygeneruje jednu podepsanou URL na záznam (až padesát na volání; obrázek každé URL se počítá jako obrázek vozidla daného měsíce) a stránka je načte jako jakýkoli jiný obrázek. U záznamu, který zůstává skladem celé měsíce, záleží na dvou nastaveních:

  • ttl_seconds: 604800 s renew: true: URL funguje i po uplynutí sedmidenního TTL a obnovení započítá obrázek jednou v měsíci, do kterého spadne, a nic dalšího, pokud už byl v tom měsíci započítán. Měsíce, kdy se na auto nikdo nepodívá, se nepočítají.
  • Idempotency-Key pro každou stránku synchronizace: opakovaný požadavek přehraje první odpověď a nic nevytvoří dvakrát.

Omezte generující klíč v nástěnce na origin CRM a URL, která unikne na jiný web, vrátí 403. Zrušením klíče zneplatníte všechny URL, které vygeneroval. Pokud jsou obrázky vozidel v tarifu na daný měsíc vyčerpány, obnovení vrátí 402 a stejná URL začne znovu fungovat po obnovení limitu nebo po navýšení tarifu. Celý životní cyklus popisuje dokumentace k podepsaným URL.

Příjem vozu a skladový seznam s TypeScript SDK
import { CarImageClient } from "@meterapp/car-image-sdk";

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

// On intake: VIN in, vehicle id on the record. Free.
const { data: decoded } = await client.decodeVin(stock.vin);
if (decoded.vehicle) {
  stock.vehicleId = decoded.vehicle.id; // veh_…, permanent; the record never spells a car again
  stock.trim = decoded.trim;            // shown next to the image, never claimed by it
}

// When the CRM draws the stock list: one signed URL per record, up to fifty per call.
// The browser loads them; the key never leaves the server.
const { data: urls } = await client.createImageUrls(
  page.map((row) => ({
    vehicle: row.vehicleId, view: "side",
    width: 640, height: 320, fit: "contain", trim: true, padding: 6, format: "auto",
  })),
  { ttlSeconds: 604_800, renew: true, renewDays: 365, idempotencyKey: `stock-list:${syncRunId}:${pageIndex}` }
);

CLI, SDK a MCP

npx @meterapp/car-image
# decode for free; the output names the vehicle id and a ready-to-run image command
npx @meterapp/car-image vin 1HGCM82633A004352
npx @meterapp/car-image vin 1HGCM82633A004352 --json | jq -r .data.vehicle.id

# a partial VIN from a faded door sticker: at least five characters, * for each unknown position
npx @meterapp/car-image vin "1HGCM826*3A" --year 2003

# the list image for one record
npx @meterapp/car-image get --vehicle veh_3qfyk22gfhsx3 --view side --width 640 --height 320 --fit contain --trim --padding 6 --format webp --out stock-4471.webp
  • SDK: client.decodeVin(vin, { year? }), client.resolve(query), client.getImage({ vehicle, … }) a client.createImageUrls(…), jak je uvedeno výše.
  • MCP: decode_vin, resolve_vehicle, get_car_image a create_car_image_urls jsou součástí základní sady nástrojů, takže asistent se skladovým systémem v kontextu dokáže odpovědět na „fotka pro skladové číslo 4471“ podle VIN v záznamu. Nastavení najdete na stránce MCP; pole a chyby dekodéru jsou popsány v dokumentaci VIN.

Často kladené otázky

Kolik stojí fotka u každého vozu na skladě?
Dekódování VIN je zdarma. Každé vozidlo v každém laku a pohledu je jeden obrázek vozidla, započítaný jednou za měsíc bez ohledu na to, jak často a v jaké velikosti se zobrazí; jeho opětovné ověření pomocí If-None-Match je zdarma. Podepsaná URL započítá svůj obrázek při vystavení a s renew: true ještě jednou v každém dalším měsíci, ve kterém je otevřena. Skupina dealerů s několika tisíci vozy skladem zobrazí měsíčně několik tisíc obrázků vozidel, proto zvolte tarif podle počtu vystavených vozů.
VIN se dekóduje, ale vehicle je null. Co teď?
Dekodér znal značku, model a rok, ale katalog pro tuto kombinaci nemá záznam: přívěs, některé užitkové podvozky, označení modelu, které zdroje ještě nezařadily. Zobrazte dekódovaná pole, prohledejte katalog pomocí GET /api/v1/vehicles?q= pro případ, že se liší pravopis, a požádejte o vozidlo na nástěnce požadavků; POST /api/v1/requests přidá hlas k již otevřenému požadavku, místo aby vytvořil duplicitní.
Pokrývá dekódování VIN i dovozy a vozidla, která se v USA nikdy neprodávala?
Dekodér využívá data vPIC od NHTSA, takže VIN od výrobce, který vozidla u NHTSA registruje, se dekóduje úplně. Vozidlo, které nikdy nebylo certifikováno pro USA, se často dekóduje jen na výrobce a rok bez modelu a některá se nedekódují vůbec. U takových vozů místo toho vyhledávejte podle technického průkazu: samotný katalog je celosvětový, od roku 1990, a jsou v něm i modely pro japonský domácí trh, například Toyota Voxy.
Zobrazuje render výbavu uvedenou v záznamu?
Ne. Katalog se řídí značkou, modelem a rokem, takže kupé EX-V6 i sedan LX se vykreslí jako stejný Accord 2003. Výbavu a body_class z dekódování uchovávejte jako text vedle obrázku a render nikdy nepopisujte jako konkrétní vůz.
Může web prodejce používat stejné URL adresy jako CRM?
Generujte je z klíče, jehož povolené originy obsahují daný web, a URL, kterou prohlížeč načte z jakéhokoli jiného webu, odpoví 403 origin_not_allowed. Požadavky bez hlavičky Referer, například z e-mailového klienta, projdou. CRM a web mohou sdílet jeden klíč a jednu sadu URL, nebo mít každý vlastní klíč, aby šlo kterýkoli z nich zrušit samostatně.