Her pazar yeri ilanına stüdyo kalitesinde araç görseli nasıl eklenir

Bir ilan sitesinin veya otomobil alışveriş kataloğunun kaderi ızgarasına bağlıdır. Her kartın, ilan oluşturulduğu anda bir görsele ihtiyacı vardır; satıcının kendi fotoğrafı ise gelirse sonradan, rastgele bir açıdan, rastgele bir garaj yolunda çekilmiş olarak gelir. Stok fotoğraflarda ise tam tersi bir sorun vardır: lisanslı basın fotoğrafları yalnızca popüler yıllardaki popüler araçlar için, üreticinin seçtiği açı ve arka planla mevcuttur; geri kalanı için hiçbir şey yoktur. 1990 ile güncel model yılı arasını kapsayan bir katalogda on binlerce boşluk vardır.

Bu siteleri geliştiren ekiplerin istediği şey, kelimenin en iyi anlamıyla sıkıcı: her model yılı için tek bir stüdyo görseli, hepsinde aynı açı ve aynı boya, kartın arka planı ne olursa olsun üzerine oturabilmesi için şeffaf ve günde on bin kez sunulabilecek kadar küçük.

Bugün API üzerinde çalışan katalog yapıları, ister ilanlarını ilk kez dolduran bir ilan sitesi, ister karşılaştırma kartlarını oluşturan bir araç alışveriş uygulaması, ister her araç için tek bir ana görsel gösteren bir mobil uygulama olsun, hepsi aynı yapıya sahiptir:

• Önce toplu doldurma, sonra damla damla. Kataloğu kapsamak için birkaç saatte binlerce render, ardından yeni model yılları ve talepler geldikçe günde birkaç tane.
• Tek açı, tek boya veya kısa bir palet. Çoğu, gümüş veya beyaz renkte front-3-4 ya da side seçer. Kullanıcının renk seçmesine izin veren bir alışveriş kataloğu, her araç için birkaç hazır renk oluşturur; her biri yeni bir iş akışı değil, yalnızca bir araç görseli daha demektir.
• Sabit bir kutuda WebP. 512 ile 1024 piksel genişliğinde, tam olarak kartın kullandığı kutu boyutunda teslim edilir; böylece ön yüz görseli asla kırpmak ya da kenarlarına boşluk eklemek zorunda kalmaz.
• Araç kimliğiyle saklanır. Renderlar ekibin kendi nesne depolama alanına veya CDN'ine yerleşir ya da sayfalar imzalı URL'leri yükler; her iki durumda da anahtar bir marka-model-yıl dizesi değil, kataloğun sabit veh_… kimliğidir.

Bu sayfanın geri kalanı, kodlarıyla birlikte bu iş akışını adım adım anlatıyor. images:read kapsamına sahip bir API anahtarınız ve kataloğunuza uygun büyüklükte bir planınız olduğu varsayılır (SSS'ye bakın).

Bir katalog oluştururken en sık karşılaşılan sorun render değil, yazımdır. Marka ve model dizelerini başka bir veritabanından üreten bir yapı, isteklerinin çoğunu 404 vehicle_not_found yanıtlarına harcayabilir: ücretsizdir ama her biri boşa giden bir gidiş-dönüş demektir ve ortaya boşluklarla dolu bir ızgara çıkar. Çözüm, neyin mevcut olduğunu kataloğun size söylemesine izin vermektir. GET /api/v1/vehicles ücretsizdir, anahtar gerektirmez ve döndürdüğü her model, dağıtımlar veya katalog sürümleri arasında asla değişmeyen sabit bir araç kimliği (veh_ artı 13 karakter) taşır. Bu kimliği ilanda saklayın ve render işlemini onunla yapın.

?make=porsche&model=911 bir modelin tüm yıllarını her yıl için bir id ile listeler; ?q= ise satıcı bir ad yazdığında serbest metin araması yapar. Aynı katalog açık @meterapp/vehicle-db paketi olarak da yayımlanır; böylece açılır menüler ve doğrulama, aynı listeye karşı çevrimdışı çalışabilir. Her iki durumda da bu adımın sonunda elinizde bir id listesi olur ve sonraki hiçbir adımda bir aracın adı bir daha harf harf yazılmaz.

Araçlarını zaten başka bir veritabanının yazımıyla adlandıran ilanlar tek çağrıda eşlenir: POST /api/v1/vehicles/check, bunlardan en fazla 2.000 tanesini bir render'ın okuyacağı şekilde okur. Her birine araç kimliğiyle, katalogda böyle bir araç yoksa en yakın gerçek araçlarla ya da tüm görünümlerde ve renklerde atlanacak bir eşleşmeme sonucuyla yanıt verir. car-image check listings.csv --out checked.csv kimlikleri dosyaya geri yazar. Ücretsizdir ve eksikleri tek tek 404 hatalarıyla keşfetmenin yerini alır.

Kartı bir kez belirleyin ve sorgu dizesine kodlayın. Aşağıda vehicle= ifadesinden sonra gelen her şey, tüm katalog için bir kez verdiğiniz bir çerçeveleme kararıdır:

• w=800&h=600&fit=contain, aracın tamamının göründüğü ve etrafında şeffaf dolgu bulunan tam 800×600 boyutunda bir görsel sunar; böylece her kartın tuvali aynı olur. fit=cover ise kutuyu doldurur ve görseli ortadan kırpar.
• trim=1&padding=8, sığdırmadan önce görseli aracın dış hatlarına göre kırpar ve uzun kenarının %8'i kadar kenar boşluğu bırakır; böylece bir Suburban ile bir Miata, kaynak karede yüzer gibi durmak yerine kutuyu aynı şekilde doldurur.
• color=silver varsayılandır ve en güvenli nötr seçenektir; 15 hazır ayardan herhangi biri veya herhangi bir hex kodu aynı şekilde, tek araç görseli olarak sayılır.
• format=webp, kayıpsız alfa kanallı en küçük kodlamadır. Tarayıcı URL'yi doğrudan yüklediğinde (imzalı URL'ler, 4. adım) format=auto, istemciye göre WebP veya PNG'yi belirler.

Yanıt; ETag, X-Image-Source (cache veya generated) ve sunulan katalog aracını belirten X-Vehicle-Id başlıklarını içerir. ETag’i dosyayla birlikte saklayın: daha sonra If-None-Match ile yapılan bir istek 304 yanıtını döndürür ve hiçbir ücret doğurmaz; gece yapılan yeniden senkronizasyonun ücretsiz kalmasını sağlayan da budur.

Toplu geriye dönük doldurmayı üç sınır belirler ve her biri sessizce başarısız olmak yerine kendini yanıt başlıklarında belli eder:

• Dakika başına istek. Free ve Pro'da anahtar başına 120, Business'ta 600, Enterprise'da 1.200; buna ek olarak tüm anahtarlar genelinde hesap başına bir limit uygulanır. Kimliği doğrulanmış her yanıt RateLimit-Remaining içerir; bir 429 yanıtı ise Retry-After içerir. Aynı anda dört ila sekiz istek fazlasıyla yeterlidir.
• Yeni araç görünümleri. Henüz hazırlamadığımız bir araç görünümü için ilk istek, görünümü her renkte gösterilebilecek şekilde hazırlarken biraz zaman alır; sonraki tüm istekler, hangi renkte olursa olsun, önbellekten sunulur. Yeni görünümlerin hazırlanması, hesabın günlük render bütçesindeki payından düşer (Free planda %2, Pro planda %10, Business planda %25, Enterprise planda %50). Bu pay aşıldığında yeni bir render code: account_generation_cap ve reset_at (UTC gece yarısı) ile 429 yanıtı döndürür, hiçbir ücret alınmaz ve önbellekteki görseller sunulmaya devam eder. Büyük bir geriye dönük doldurma tek bir akşamda değil, birkaç akşamda tamamlanır.
• Aylık araç görselleri. Free 100, Pro 2.500, Business 10.000 görsel içerir; Enterprise görüşmeyle belirlenir. Bu kota aşıldıktan sonra, bu ay henüz sayılmamış bir görsel için yapılan istek 402 (plan_image_limit) yanıtını döndürür ve hiçbir şey sayılmaz; bu ay zaten sayılmış bir görsel her zaman sunulur, böylece canlı bir ızgara asla bozulmaz.

Render hataları (502) araç görselini otomatik olarak iade eder, aynı yeni varyant için eşzamanlı istekler tek bir render'ı paylaşır ve basit bir GET güvenle yeniden denenebilir. SDK, Retry-After değerine uyarak 429 ve 503 yanıtlarını sizin için yeniden dener ve 402 yanıtını asla yeniden denemez.

Görseli alışveriş yapan kullanıcının önüne getirmenin iki iyi yolu var ve katalog projeleri ikisini de kullanıyor:

• Baytları saklayın. Her render'ı kendi nesne depolamanıza veya CDN'inize araç kimliğiyle yazın ve diğer tüm varlıklar gibi sunun. Milyonlarca kez görüntülenen bir ızgara için doğru çözüm budur: her yüklemede bize çağrı yapılmaz ve ücretli plandaki lisans, ürününüzü sunmak için sakladığınız kopyaları kapsar.
• İmzalı URL'ler oluşturun. POST /api/v1/image-urls çağrı başına en fazla elli görsel alır, her URL'nin görselini oluşturulduğu anda o ayın araç görseli olarak sayar ve tarayıcının doğrudan yüklediği, anahtar içermeyen URL'ler döndürür. ttl_seconds değerini en fazla yedi gün olarak ayarlayın; bundan daha uzun süre yayında kalan ilan sayfaları için renew: true ekleyin (bir yenileme, görseli denk geldiği ayda bir kez sayar; o ay zaten sayılmışsa başka bir şey saymaz). Anahtarı panelde sitenizin origin'leriyle sınırlayın; başka bir yere kopyalanan URL 403 döndürür.

Toplu oluştururken her ilan sayfası için bir Idempotency-Key gönderin: aynı anahtar ve gövdeyle yeniden denenen bir çağrı ilk yanıtı tekrar döndürür ve hiçbir şeyi yeniden saymaz.

Önce arayın: GET /api/v1/vehicles?q= bir modeli adına, önekine veya bulanık eşleşmeyle bulur; POST /api/v1/images/resolve ise serbest metinli bir ifadeyi, buna göre hareket edebileceğiniz bir güven puanıyla birlikte kesin parametrelere dönüştürür. Bundan sonra hâlâ eksik olanların yeri talep panosudur: POST /api/v1/requests talebi oluşturur ya da aynı marka, model ve yıl için açık bir talep varsa yenisini oluşturmak yerine ona oy verir. Kataloğun kendisi açık kaynaktır ve eklemeler tüm müşterilere sunulur.

Tüm işlem hattı hiç kod yazmadan CLI üzerinden çalışır; API'deki birden fazla katalog da ilk verilerini bu şekilde aldı:

• SDK: listelemek için client.vehicles({ year, makeId }), render için client.getImage({ vehicle, … }), imzalı URL grupları için client.createImageUrls(…). Tüm parametreler için görsel belgelerine bakın.
• MCP: https://carimage.dev/api/mcp adresine bağlı bir asistan aynı kataloğa (search_vehicles, resolve_vehicle) ve aynı görsellere (get_car_image, create_car_image_urls) erişir; bu, bir aracı elle ekleyen bir küratör için doğru seçenektir, binlerce kaydın toplu doldurulması içinse yanlış seçenektir: bunun için CLI'ı ya da SDK'yı kullanın ve asistanı geride kalanlara saklayın. Kurulum bilgileri MCP sayfasında.