Zo zet u bij elke marktplaatsadvertentie een studioafbeelding van de auto

Een advertentiesite of autocatalogus staat of valt met zijn raster. Elke kaart heeft een afbeelding nodig zodra de advertentie bestaat, en de eigen foto van de verkoper komt later, als die al komt, vanuit een willekeurige hoek op een willekeurige oprit. Stockfotografie heeft het omgekeerde probleem: er bestaat een gelicentieerde persfoto voor de populaire auto's in de populaire jaren, vanuit de hoek en tegen de achtergrond die de fabrikant koos, en voor niets anders. Een catalogus die loopt van 1990 tot het huidige modeljaar heeft tienduizenden gaten.

Wat de teams achter deze sites willen, is saai op de beste manier: één studioafbeelding per modeljaar, voor allemaal dezelfde hoek en dezelfde lakkleur, transparant zodat die op elke kaartachtergrond past, en klein genoeg om tienduizend keer per dag te serveren.

De catalogusbuilds die vandaag op de API draaien, hebben allemaal dezelfde opzet, of het nu gaat om een advertentiesite die haar aanbod vult, een autokoop-app die vergelijkingskaarten rendert of een mobiele app die één hero-afbeelding per voertuig toont:

• Eerst een backfill, dan een gestaag stroompje. Duizenden renders in een paar uur om de catalogus te dekken, daarna een handvol per dag naarmate er nieuwe modeljaren en aanvragen binnenkomen.
• Eén hoek, één lakkleur of een klein palet. De meesten kiezen front-3-4 of side in zilver of wit. Een winkelcatalogus waarin de gebruiker een kleur kiest, rendert een paar presets per voertuig; elke preset is één voertuigafbeelding extra, geen nieuwe pipeline.
• WebP in een vast kader. 512 tot 1024 pixels breed, geleverd in precies het kader dat de kaart gebruikt, zodat de front-end nooit hoeft bij te snijden of zwarte balken hoeft toe te voegen.
• Opgeslagen op voertuig-id. De renders komen terecht in de eigen object store of CDN van het team, of de pagina's laden signed URLs; hoe dan ook is de sleutel de stabiele veh_…-id uit de catalogus, niet een merk-model-jaar-string.

De rest van deze pagina beschrijft die pipeline stap voor stap, met de code. Er wordt uitgegaan van een API-sleutel met de scope images:read en een abonnement dat past bij de omvang van de catalogus (zie de FAQ).

De meest voorkomende fout bij het bouwen van een catalogus is niet het renderen, maar de spelling. Een build die merk- en modelnamen uit een andere database genereert, kan het grootste deel van zijn verzoeken kwijt zijn aan 404 vehicle_not_found: gratis, maar telkens een verspilde round trip, en een raster vol gaten. De oplossing: laat de catalogus u vertellen wat er bestaat. GET /api/v1/vehicles is gratis, vereist geen sleutel, en elk model dat het retourneert heeft een stabiele voertuig-id (veh_ plus 13 tekens) die nooit verandert tussen deploys of catalogusreleases. Sla die id op bij de advertentie en render op basis daarvan.

?make=porsche&model=911 toont elk bouwjaar van één model met een id per jaar, en ?q= zoekt op vrije tekst wanneer een verkoper een naam typt. Dezelfde catalogus is gepubliceerd als het open pakket @meterapp/vehicle-db, zodat dropdowns en validatie offline tegen exact dezelfde lijst kunnen draaien. Hoe dan ook heeft u aan het eind van deze stap een lijst met ids, en hoeft niets verderop in de keten ooit nog een auto uit te spellen.

Advertenties die hun auto's al benoemen in de spelling van een andere database, worden in één call gekoppeld: POST /api/v1/vehicles/check leest er maximaal 2.000 op dezelfde manier als een render dat zou doen en beantwoordt elk ervan met het voertuig-id, de dichtstbijzijnde echte voertuigen als de catalogus zo'n auto niet heeft, of een misser die u in elke weergave en kleur kunt overslaan. car-image check listings.csv --out checked.csv schrijft de id's terug in het bestand. Het is gratis, en het voorkomt dat u de gaten één 404 tegelijk ontdekt.

Bepaal de kaart één keer en leg die vast in de querystring. Alles na vehicle= hieronder is een keuze over de framing die u één keer maakt voor de hele catalogus:

• w=800&h=600&fit=contain levert precies 800×600 op, met de hele auto zichtbaar en transparante opvulling eromheen, zodat elke kaart hetzelfde canvas heeft. fit=cover vult in plaats daarvan het vak en snijdt vanuit het midden bij.
• trim=1&padding=8 snijdt bij tot de omtrek van de auto voordat er wordt ingepast, met 8% van de langste zijde als marge, zodat een Suburban en een Miata het kader op dezelfde manier vullen in plaats van in het bronbeeld te zweven.
• color=silver is de standaard en de veiligste neutrale kleur; elk van de 15 presets of elke hexwaarde telt hetzelfde: één voertuigafbeelding.
• format=webp is de kleinste codering met een verliesvrij alfakanaal. Wanneer een browser de URL rechtstreeks laadt (ondertekende URL's, stap 4), kiest format=auto per client tussen WebP en PNG.

Het antwoord bevat ETag, X-Image-Source (cache of generated) en X-Vehicle-Id, het catalogusvoertuig dat is geleverd. Bewaar de ETag bij het bestand: een latere request met If-None-Match krijgt 304 als antwoord en kost niets. Zo blijft een nachtelijke hersynchronisatie gratis.

Drie limieten bepalen een backfill, en elk ervan maakt zich kenbaar in headers in plaats van stilletjes te falen:

• Verzoeken per minuut. 120 per sleutel bij Free en Pro, 600 bij Business, 1.200 bij Enterprise, plus een limiet per account over alle sleutels heen. Elke geauthenticeerde respons bevat RateLimit-Remaining; een 429 bevat Retry-After. Vier tot acht gelijktijdige verzoeken is ruim voldoende.
• Nieuwe voertuigweergaven. Het eerste verzoek voor een voertuigweergave die we nog niet hebben voorbereid, duurt even terwijl we die voorbereiden, zodat die in elke kleur kan worden getoond; elk volgend verzoek, in welke kleur ook, wordt vanuit de cache geleverd. Het voorbereiden van nieuwe weergaven gaat af van het aandeel van het account in het dagelijkse renderbudget (2% bij Free, 10% bij Pro, 25% bij Business, 50% bij Enterprise). Daarboven geeft een nieuwe render 429 terug met code: account_generation_cap en reset_at (middernacht UTC), wordt er niets in rekening gebracht en worden gecachete afbeeldingen gewoon geleverd. Een grote backfill duurt een paar avonden, niet één.
• Voertuigafbeeldingen per maand. Free bevat er 100, Pro 2.500, Business 10.000; over Enterprise wordt onderhandeld. Boven dat tegoed krijgt een verzoek om een afbeelding die deze maand nog niet is geteld het antwoord 402 (plan_image_limit) en wordt er niets geteld; een afbeelding die deze maand al is geteld, wordt altijd geleverd, zodat een live raster nooit breekt.

Mislukte renders (502) geven hun voertuigafbeelding automatisch terug, gelijktijdige verzoeken voor dezelfde nieuwe variant delen één render, en een gewone GET kan veilig opnieuw worden geprobeerd. De SDK probeert 429 en 503 automatisch opnieuw, met inachtneming van Retry-After, en probeert een 402 nooit opnieuw.

Er zijn twee goede manieren om de afbeelding bij een koper te krijgen, en bij het opbouwen van catalogi worden ze allebei gebruikt:

• Sla de bytes op. Schrijf elke render naar uw eigen objectopslag of CDN onder het voertuig-id en lever hem uit zoals elk ander asset. Dit is de juiste keuze voor een raster dat miljoenen keren wordt weergegeven: geen aanroep naar ons per keer laden, en de licentie van een betaald abonnement dekt kopieën die u bewaart om uw product te bedienen.
• Maak ondertekende URL’s aan. POST /api/v1/image-urls verwerkt tot vijftig afbeeldingen per aanroep, telt de afbeelding van elke URL als voertuigafbeelding van de maand wanneer de URL wordt aangemaakt, en geeft URL’s zonder sleutel terug die de browser direct laadt. Stel ttl_seconds in op maximaal zeven dagen; voeg renew: true toe voor advertentiepagina’s die langer online blijven (een verlenging telt de afbeelding één keer in de maand waarin die plaatsvindt, en niets extra als de afbeelding die maand al was geteld). Beperk de sleutel in het dashboard tot de origins van uw site, en een URL die elders wordt gekopieerd, geeft 403 terug.

Stuur een Idempotency-Key per pagina advertenties mee wanneer u in batches aanmaakt: een herhaalde aanroep met dezelfde sleutel en body geeft het eerste antwoord opnieuw terug en telt niets opnieuw mee.

Zoek eerst: GET /api/v1/vehicles?q= vindt een model op naam, prefix of fuzzy match, en POST /api/v1/images/resolve zet een vrije tekst om in exacte parameters met een betrouwbaarheidsscore waarop u kunt handelen. Wat daarna nog ontbreekt, hoort op het verzoekenbord: POST /api/v1/requests maakt het verzoek aan of, als er al een open verzoek is voor hetzelfde merk, model en bouwjaar, stemt daarop in plaats van een duplicaat te maken. De catalogus zelf is open source en toevoegingen komen beschikbaar voor elke klant.

De hele pipeline draait vanuit de CLI zonder enige code, en zo is meer dan één catalogus op de API gevuld:

• SDK: client.vehicles({ year, makeId }) om op te sommen, client.getImage({ vehicle, … }) om te renderen, client.createImageUrls(…) voor batches signed URL's. Zie de documentatie over afbeeldingen voor alle parameters.
• MCP: een assistent die verbonden is met https://carimage.dev/api/mcp heeft dezelfde catalogus (search_vehicles, resolve_vehicle) en dezelfde renders (get_car_image, create_car_image_urls). Dat is het juiste hulpmiddel voor een curator die handmatig een voertuig toevoegt, en het verkeerde voor een backfill van duizenden voertuigen: gebruik daarvoor de CLI of de SDK en bewaar de assistent voor de achterblijvers. De installatie staat op de MCP-pagina.