Jak dodać studyjne zdjęcie samochodu do każdego ogłoszenia w serwisie

O sukcesie serwisu ogłoszeniowego czy katalogu samochodów decyduje siatka ofert. Każda karta potrzebuje zdjęcia od chwili utworzenia ogłoszenia, a własne zdjęcie sprzedającego pojawia się później – o ile w ogóle – zrobione pod przypadkowym kątem, na przypadkowym podjeździe. Zdjęcia stockowe mają odwrotny problem: licencjonowane zdjęcie prasowe istnieje dla popularnych samochodów z popularnych roczników, pod kątem i na tle wybranym przez producenta, i dla niczego więcej. Katalog obejmujący lata od 1990 do bieżącego rocznika ma dziesiątki tysięcy luk.

Zespoły budujące takie serwisy chcą czegoś nudnego w najlepszym sensie: jednego studyjnego obrazu na rocznik modelu, z tym samym kątem i tym samym lakierem dla wszystkich, przezroczystego, żeby pasował do dowolnego tła karty, i na tyle lekkiego, by serwować go dziesięć tysięcy razy dziennie.

Wszystkie katalogi budowane dziś na tym API mają ten sam schemat, niezależnie od tego, czy to serwis ogłoszeniowy zasilający swoje ogłoszenia, aplikacja zakupowa renderująca karty porównawcze, czy aplikacja mobilna pokazująca jeden główny obraz każdego pojazdu:

• Najpierw masowe uzupełnienie, potem pojedyncze zlecenia. Tysiące renderów w kilka godzin, by objąć cały katalog, a potem kilka dziennie, w miarę pojawiania się nowych roczników i zapytań.
• Jedno ujęcie, jeden lakier lub krótka paleta. Większość wybiera front-3-4 lub side w kolorze srebrnym lub białym. Katalog sklepowy, w którym użytkownik wybiera kolor, renderuje kilka gotowych kolorów na pojazd; każdy to jeden obraz pojazdu więcej, a nie nowy proces.
• WebP w stałym polu. Szerokość od 512 do 1024 pikseli, dostarczane dokładnie w wymiarach, których używa karta, więc front end nigdy nie przycina obrazu ani nie dodaje pasów.
• Przechowywanie według id pojazdu. Rendery trafiają do własnego magazynu obiektów lub CDN zespołu albo strony wczytują podpisane URL-e; tak czy inaczej kluczem jest stabilny identyfikator veh_… z katalogu, a nie ciąg marka-model-rok.

Dalsza część tej strony opisuje ten proces krok po kroku, wraz z kodem. Zakłada ona klucz API z zakresem images:read i plan dopasowany do wielkości katalogu (zob. FAQ).

Najczęstszą przyczyną błędów przy budowie katalogu nie jest renderowanie, tylko pisownia. Katalog, który generuje nazwy marek i modeli z innej bazy danych, może zużyć większość żądań na 404 vehicle_not_found: bezpłatnie, ale każde to zmarnowane zapytanie, a w siatce zostają dziury. Rozwiązanie: niech katalog sam powie, co istnieje. GET /api/v1/vehicles jest bezpłatne, nie wymaga klucza, a każdy zwrócony model ma stały identyfikator pojazdu (veh_ plus 13 znaków), który nie zmienia się między wdrożeniami ani wydaniami katalogu. Wystarczy zapisać ten identyfikator przy ogłoszeniu i renderować na jego podstawie.

?make=porsche&model=911 zwraca wszystkie roczniki jednego modelu z osobnym id dla każdego rocznika, a ?q= przeszukuje dowolny tekst, gdy sprzedawca wpisuje nazwę. Ten sam katalog jest publikowany jako otwarty pakiet @meterapp/vehicle-db, więc listy rozwijane i walidacja mogą działać offline na identycznej liście. Tak czy inaczej, pod koniec tego kroku mają Państwo listę id i na dalszych etapach nic już nigdy nie musi przepisywać nazwy samochodu.

Ogłoszenia, które już nazywają swoje samochody zgodnie z pisownią innej bazy danych, mapuje się jednym wywołaniem: POST /api/v1/vehicles/check odczytuje do 2000 z nich tak, jak zrobiłby to render, i dla każdego zwraca identyfikator pojazdu, najbliższe rzeczywiste pojazdy, gdy katalog nie zawiera takiego samochodu, albo brak dopasowania, który należy pominąć we wszystkich widokach i kolorach. car-image check listings.csv --out checked.csv zapisuje identyfikatory z powrotem do pliku. Jest to bezpłatne i zastępuje odkrywanie luk po jednym 404 naraz.

Wygląd karty ustala się raz i koduje w query stringu. Wszystko po vehicle= poniżej to decyzja o kadrowaniu podejmowana jednorazowo dla całego katalogu:

• w=800&h=600&fit=contain zwraca obraz o wymiarach dokładnie 800×600, z widocznym całym samochodem i przezroczystym marginesem wokół, dzięki czemu każda karta ma to samo płótno. fit=cover wypełnia natomiast cały obszar i przycina obraz od środka.
• trim=1&padding=8 przycina obraz do konturu samochodu przed dopasowaniem, z marginesem równym 8% jego dłuższego boku, dzięki czemu Suburban i Miata wypełniają ramkę tak samo, zamiast unosić się w kadrze źródłowym.
• color=silver to wartość domyślna i najbezpieczniejszy neutralny kolor; każdy z 15 predefiniowanych kolorów lub dowolny kod hex liczy się tak samo, jako jeden obraz pojazdu.
• format=webp to najmniejsze kodowanie z bezstratnym kanałem alfa. Gdy przeglądarka ładuje URL bezpośrednio (podpisane adresy URL, krok 4), format=auto negocjuje WebP lub PNG osobno dla każdego klienta.

Odpowiedź zawiera nagłówki ETag, X-Image-Source (cache lub generated) oraz X-Vehicle-Id, czyli pojazd z katalogu, który został zwrócony. ETag należy przechowywać razem z plikiem: późniejsze żądanie z If-None-Match zwraca 304 i nic nie kosztuje – dzięki temu nocna ponowna synchronizacja pozostaje bezpłatna.

Masowe uzupełnianie danych kształtują trzy limity, a każdy z nich sygnalizuje się w nagłówkach, zamiast zawodzić po cichu:

• Żądania na minutę. 120 na klucz w planach Free i Pro, 600 w Business, 1200 w Enterprise, a do tego limit na konto obejmujący wszystkie klucze. Każda uwierzytelniona odpowiedź zawiera nagłówek RateLimit-Remaining; odpowiedź 429 zawiera Retry-After. Od czterech do ośmiu równoległych żądań w zupełności wystarczy.
• Nowe widoki pojazdów. Pierwsze żądanie widoku pojazdu, którego jeszcze nie przygotowaliśmy, trwa chwilę, ponieważ przygotowujemy go tak, by można go było wyświetlić w dowolnym kolorze; każde kolejne żądanie, w dowolnym kolorze, jest obsługiwane z pamięci podręcznej. Przygotowywanie nowych widoków korzysta z udziału konta w dziennym budżecie renderowania (2% w planie Free, 10% w Pro, 25% w Business, 50% w Enterprise). Po jego wyczerpaniu nowy render zwraca 429 z code: account_generation_cap i reset_at (północ UTC), nic nie jest naliczane, a obrazy z pamięci podręcznej są nadal serwowane. Duży import zaległych danych rozkłada się na kilka wieczorów, a nie jeden.
• Obrazy pojazdów miesięcznie. Free obejmuje 100, Pro 2500, Business 10 000; Enterprise jest negocjowany. Po wyczerpaniu limitu żądanie obrazu, który nie został jeszcze policzony w tym miesiącu, zwraca 402 (plan_image_limit) i niczego nie nalicza; obraz już policzony w tym miesiącu jest zawsze serwowany, więc działająca siatka ogłoszeń nigdy się nie psuje.

Błędy renderowania (502) automatycznie zwracają naliczony obraz pojazdu, równoczesne żądania tego samego nowego wariantu współdzielą jeden render, a zwykłe GET można bezpiecznie ponawiać. SDK samo ponawia 429 i 503, respektując Retry-After, i nigdy nie ponawia 402.

Są dwa dobre sposoby, by pokazać obraz kupującemu, a wdrożenia katalogowe korzystają z obu:

• Przechowywanie plików. Każdy render należy zapisać we własnym magazynie obiektów lub CDN pod identyfikatorem pojazdu i serwować jak każdy inny zasób. To właściwe rozwiązanie dla siatki wyświetlanej miliony razy: brak wywołań do nas przy każdym załadowaniu, a licencja w planie płatnym obejmuje kopie przechowywane na potrzeby Państwa produktu.
• Generowanie podpisanych URL-i. POST /api/v1/image-urls przyjmuje do pięćdziesięciu obrazów na wywołanie, liczy obraz każdego URL-a jako obraz pojazdu w danym miesiącu w chwili wygenerowania i zwraca URL-e bez klucza, które przeglądarka wczytuje bezpośrednio. ttl_seconds można ustawić maksymalnie na siedem dni; dla stron ogłoszeń istniejących dłużej należy dodać renew: true (odnowienie liczy obraz raz w miesiącu, w którym nastąpi, i nic więcej, jeśli obraz został już policzony w tym miesiącu). Po ograniczeniu klucza w panelu do domen (origin) witryny URL skopiowany gdzie indziej zwraca 403.

Przy generowaniu partiami należy wysyłać Idempotency-Key dla każdej strony ogłoszeń: ponowione wywołanie z tym samym kluczem i treścią odtwarza pierwszą odpowiedź i niczego ponownie nie nalicza.

Najpierw wyszukiwanie: GET /api/v1/vehicles?q= znajduje model po nazwie, prefiksie lub dopasowaniu przybliżonym, a POST /api/v1/images/resolve zamienia dowolną frazę tekstową na dokładne parametry wraz z poziomem pewności, na którego podstawie można działać. To, czego nadal brakuje, należy zgłosić na tablicy zgłoszeń: POST /api/v1/requests tworzy zgłoszenie, a jeśli istnieje już otwarte zgłoszenie dla tej samej marki, modelu i roku, oddaje na nie głos zamiast tworzyć duplikat. Sam katalog jest open source, a nowe pozycje trafiają do wszystkich klientów.

Cały proces działa z poziomu CLI bez ani jednej linijki kodu — w ten sposób zasilono niejeden katalog korzystający z API:

• SDK: client.vehicles({ year, makeId }) do wyliczania, client.getImage({ vehicle, … }) do renderowania, client.createImageUrls(…) do partii podpisanych URL-i. Wszystkie parametry opisuje dokumentacja obrazów.
• MCP: asystent połączony z https://carimage.dev/api/mcp ma dostęp do tego samego katalogu (search_vehicles, resolve_vehicle) i tych samych renderów (get_car_image, create_car_image_urls). To właściwe narzędzie dla kuratora dodającego pojazd ręcznie, ale niewłaściwe do uzupełniania tysięcy rekordów wstecz: do tego należy użyć CLI lub SDK, a asystenta zostawić na pojedyncze zaległe przypadki. Konfiguracja jest opisana na stronie MCP.