Car Image API

Zákazníci · Studia pro polepy, tónování skel a PPF

Jak zobrazit náhled polepu, tónování nebo PPF přímo na voze zákazníka

Jak dílny zaměřené na polepy, tónování a ochranné fólie laku využívají bílé základní rendery, přesné hex barvy laku a 3D modely, aby zákazníkovi ukázaly zakázku na jeho vlastním autě ještě před zahájením práce.

Průvodce pro aftermarket

Problém: zákazník to chce vidět na svém autě

Polepovací dílna, studio na tónování skel nebo firma instalující ochrannou fólii laku prodává něco, co zákazník neuvidí, dokud není hotovo. Portfolio ukazuje auta jiných lidí. Vzorník výrobce ukazuje materiál na ploché kartě. Prodej uzavře až zákazníkovo vlastní M4 z roku 2021 v přesně té saténově šedé, nad kterou váhá – a taková fotka neexistuje, protože zakázka ještě neproběhla.

Stejná mezera se objevuje i dál v řetězci. Řezač fólií potřebuje čistý obrys předního nárazníku pro modelový rok, který knihovna šablon zatím nepokrývá. Konfigurátor potřebuje otočný náhled auta v základní barvě, přes kterou může designér malovat. Všichni tři potřebují totéž: studiový obrázek konkrétní značky, modelu a roku v laku, který si zvolí, bez čehokoli v pozadí.

Tři způsoby, jak rendery využívají dílny

Integrace pro polepy, tónování a ochranné fólie, které dnes API využívají, dělají tři věci, někdy všechny tři najednou:

  • Bílý základ a materiál navrch. Vyrenderujte modelový rok zákazníkova vozu v color=white na průhledném PNG a fólii, tónování nebo potištěný design přes něj složte v prohlížeči. Alfa kanál PNG tvoří obrys auta.
  • Lak podle hex kódu. Pro jednobarevný polep nebo přelakování vynechte skládání vrstev: color=686c70 vrátí vůz rovnou v tomto laku, se skly a koly beze změny, jako jeden obrázek vozidla, stejně jako u předvolby.
  • 3D model pro otočnou prezentaci. POST /api/v1/3d vytvoří texturovaný GLB, USDZ a FBX vozidla ve zvolené barvě, jednou pro každé vozidlo a barvu. Ke zveřejněnému modelu získáte dvouřádkový embed pro stránku s cenovou nabídkou a USDZ, který si zákazník může otevřít v AR na iPhonu.

Jedna dílna spouští své dávky přes konektor ChatGPT místo kódu, což je čtvrtý vzorec, který si zaslouží vlastní sekci níže.

Bílý základní render a materiál navrch

Polep nahrazuje lak, proto začněte s co nejmenším množstvím laku. color=white dává nejsvětlejší neutrální karoserii se zachovaným studiovým stínováním; přímý pohled side ukazuje největší část boku s nejmenším perspektivním zkreslením, což náhled materiálu potřebuje. Požádejte o png (nebo webp), aby se zachoval alfa kanál, a o největší velikost, 1024, aby šlo náhled přiblížit.

Základní render a totéž auto v laku podle hex kódu
# the customer's exact model year, in white: the base every material goes on top of
curl --fail-with-body -H "Authorization: Bearer $CAR_IMAGE_API_KEY" \
  "https://carimage.dev/api/v1/images/car?vehicle=veh_0ta0ejj0qad2w&view=side&color=white&w=1024&format=png" \
  -o m4-side-white.png

# a solid-color wrap or a factory paint, by hex: the API recolors the paint and leaves glass, trim and wheels alone
curl --fail-with-body -H "Authorization: Bearer $CAR_IMAGE_API_KEY" \
  "https://carimage.dev/api/v1/images/car?vehicle=veh_0ta0ejj0qad2w&view=side&color=686c70&w=1024&format=png" \
  -o m4-side-nardo.png

U texturovaného materiálu stačí na skládání několik řádků kódu pro canvas: render se jednou vykreslí jako maska, materiál se nanese jen tam, kde je auto, a render se vykreslí znovu v režimu násobení (multiply), takže jeho stínování a odlesky prosvítají materiálem zpět.

Nanesení materiálu na základ v prohlížeči
// A textured material (carbon, chrome, a printed design) goes on in the browser.
// The white render is the mask: paint the material only where the car is, then let
// the render's own shading through.
const car = await loadImage(whiteBaseUrl); // transparent PNG from the API
const ctx = canvas.getContext("2d");
canvas.width = car.width;
canvas.height = car.height;

ctx.drawImage(car, 0, 0);
ctx.globalCompositeOperation = "source-atop"; // keep the car's alpha
ctx.fillStyle = ctx.createPattern(materialSwatch, "repeat");
ctx.fillRect(0, 0, canvas.width, canvas.height);
ctx.globalCompositeOperation = "multiply"; // shading, reflections and panel lines come back
ctx.drawImage(car, 0, 0);
// The whole silhouette is covered, glass and wheels included: the API ships the car's
// alpha, not per-panel masks. Good enough for a quote; a solid color should use color=<hex> instead.

Jak najít lak nebo barvu fólie podle hex kódu

Od doby, kdy jsou laky přebarvením jednoho neutrálního renderu, přijímá color vedle názvů předvoleb (15) libovolný šestimístný hex kód: color=686c70 bez mřížky v URL, "color": "#686c70" v JSON. Vyhledejte vzorek výrobce nebo tovární kód laku zákazníka a předejte ho. Přebarvení se použije pouze na lak, takže skla, světla, lišty a kola zůstanou, jak jsou, a právě v tom je rozdíl mezi náhledem polepu a tónovanou fotkou. Každý hex kód je další varianta v mezipaměti a jeden obrázek vozidla za měsíc, takže paleta dvaceti kandidátů pro jedno auto v jednom pohledu znamená dvacet obrázků vozidel.

3D model pro otočné zobrazení a AR

Když se auto na stránce s cenovou nabídkou potřebuje otáčet, objednejte model. POST /api/v1/3d přijme id vozidla a barvu, strhne 100 kreditů a sestaví texturovaný GLB, jeho verzi pro prohlížeč, USDZ a FBX a k tomu náhled. První model vozidla trvá 10–20 minutes; každá další barva téhož vozidla jen přetexturuje stejnou síť za 1–2 minutes. Objednání vozidla a barvy, které už máte, je zdarma (billing.already_owned: true), takže dílna může svůj konfigurátor stavět na stejném bílém základu pro každou zakázku.

Objednejte ho v bílé a hned ho zveřejněte
curl -X POST https://carimage.dev/api/v1/3d \
  -H "Authorization: Bearer $CAR_IMAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: wrap-quote-4471" \
  -d '{"vehicle": "veh_0ta0ejj0qad2w", "color": "white", "publish": true}'
202 Accepted (zkráceno)
{
  "data": {
    "id": "8c1d6b8e-2b4a-4f6e-9a2e-1f3c5d7e9b01",
    "object": "3d_model",
    "status": "queued",
    "progress": 0,
    "vehicle": {
      "id": "veh_0ta0ejj0qad2w",
      "make": "bmw",
      "model": "m4",
      "year": 2021
    },
    "color": "white",
    "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,
    "credits_remaining": 24900,
    "already_owned": false
  },
  "request_id": "req_01j9y…"
}

publish: true poskytne modelu URL bez klíče na našem CDN a embed ještě předtím, než je hotový; prvek zobrazuje průběh, dokud soubory nedorazí. Nastavte view na kterýkoli z devíti úhlů kamery pro úvodní záběr, spin pro otočný talíř, backdrop pro podlahu studia a ar, chcete-li nabídnout USDZ iPhonům a GLB Androidu prostřednictvím vestavěného AR zobrazení prohlížeče. FBX je pro designéra: otevřete jej v Blenderu nebo v nástroji pro návrh polepů, namalujte grafiku na UV a zákazník uvidí svůj vlastní návrh na svém vlastním autě.

Vložený widget na stránce cenové nabídky
<script src="https://carimage.dev/embed/3d.js" async></script>
<car-3d model="m3d_…" view="front-3-4" spin backdrop="studio" ar alt="2021 BMW M4 in white"></car-3d>

Spuštění dávky z ChatGPT nebo Claude

Ne každé studio má vývojáře a jednou z nejvytíženějších integrací API je provozovatel, který si o rendery říká asistentovi. Přidejte https://carimage.dev/api/mcp jako konektor (ChatGPT a Claude se přihlašují přes OAuth; člověk schválí oprávnění na obrazovce) a asistent získá stejné nástroje jako program: resolve_vehicle, který převede „Audi S3 cabriolet 2014, šedé, z boku“ na přesné parametry, get_car_image pro jeden render, create_car_image_urls pro až padesát podepsaných URL v jednom volání a create_3d_model pro otočný 3D náhled.

Aby dávka zadaná přes asistenta proběhla dobře, pomáhají dvě věci:

  • Pro každou dávku předávejte idempotency_key. Asistenti pokusy opakují. S klíčem vrátí opakované volání create_car_image_urls první výsledek (idempotent_replayed: true) a nic nenaúčtuje.
  • Počítejte s rozpočtem na rendery, nejen s limitem požadavků. Pohledy na vozidla, o které dosud nikdo nepožádal, je nutné nejprve připravit a jejich příprava čerpá z denního podílu kapacity účtu (10 % u Pro). Dávka několika set nových aut ve třech pohledech ho může vyčerpat; nástroj pak odpoví časem pro opakování a reset_at, nic se neúčtuje a obrázky z mezipaměti se dál doručují. Rozložte dávku na večer nebo dva, nebo přejděte na Business s větším podílem.

Nastavení pro jednotlivé klienty a úplný seznam nástrojů najdete na stránce MCP.

CLI, SDK a MCP

npx @meterapp/car-image
# the white base and a hex paint, straight to files
npx @meterapp/car-image get --vehicle veh_0ta0ejj0qad2w --view side --color white --width 1024 --out m4-side-white.png
npx @meterapp/car-image get --vehicle veh_0ta0ejj0qad2w --view side --color 686c70 --width 1024 --out m4-side-nardo.png

# the 3D model: published at once, polled until ready, every file downloaded
npx @meterapp/car-image 3d create --vehicle veh_0ta0ejj0qad2w --color white --publish --wait --out ./models
S TypeScript SDK
import { CarImageClient } from "@meterapp/car-image-sdk";

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

// 100 credits the first time. Ordering the same vehicle in the same color again
// answers billing.already_owned: true and charges nothing.
const { data: model } = await client.create3dModel({ vehicle: "veh_0ta0ejj0qad2w" }, { color: "white", publish: true });
const ready = await client.wait3dModel(model.id, { onProgress: (m) => console.log(m.stage, m.progress) });

// FBX for the designer's tool of choice, USDZ for the customer's iPhone, glb_web for the page.
const fbx = await client.download3dModel(ready.id, "fbx");
const embedHtml = ready.public?.embed.html;
  • MCP: get_car_image a create_car_image_urls v základní sadě nástrojů, create_3d_model, get_3d_model a publish_3d_model s ?toolset=all; každý obrazový nástroj přijímá vehicle a hex color.
  • Dokumentace 3D popisuje webhooky (jeden podepsaný POST, jakmile je model hotový), velikosti souborů a všechny atributy pro vložení; sekce Barvy na stránce Obrázky popisuje pravidla pro barvy laku.

Často kladené otázky

Stojí vlastní hex barva víc než předvolená?
Ne. Každá barva je přebarvením jednoho připraveného pohledu daného vozidla, takže předvolba, vyhledaný tovární kód i vzorek výrobce fólií se každý počítá jako jeden obrázek vozidla. Hex kód, který odpovídá vzorku předvolby, je touto předvolbou.
Je render dost přesný na to, aby se podle něj dala řezat fólie?
Ne. Rendery jsou studiové vizualizace značky, modelu a roku, ne data CAD ani fotografie výrobce: katalog nerozlišuje výbavy a linie dílů karoserie se mohou mezi dvěma pohledy na totéž auto lišit. Používejte je k tomu, abyste zákazníkovi ukázali jeho auto a nacenili zakázku; střihy vyřezávejte podle šablony nebo přímo podle vozidla.
Můžeme dostat auto bez laku, nebo jen okna?
Nejblíže prázdné šabloně je color=white na průhledném PNG a alfa kanál PNG tvoří siluetu auta. API neposkytuje masky pro jednotlivé díly karoserie ani skla. U jednobarevného polepu nechte práci na color=<hex>: přebarví lak a skla, lišty a kola ponechá beze změny.
Které pohledy by měla používat nabídka na tónování nebo PPF?
Přímé pohledy: side (nebo side-right) pro skla dveří a boky, front pro pruh na čelním skle, kapotu a nárazník, rear pro zadní sklo. Na tříčtvrteční pohledy zákazníci reagují nejvíc, proto použijte front-3-4 pro hlavní obrázek a přímé pohledy vedle jednotlivých položek.
Patří 3D model nám?
Je licencovaný stejně jako rendery: platíte jednou za vozidlo a barvu v rámci účtu, opětovné objednání je zdarma a můžete ho používat ve svém produktu a uchovávat na svých serverech, a to i po skončení tarifu. Každá další barva vozidla, které už máte, jen změní texturu téže sítě modelu a publikováním získá model zdarma URL adresy bez klíče a možnost vložení (embed).