Kart, kiracının alacağı arabanın tam kendisini gösterebilir mi?

Hayır, denememeli de. Bir sınıf “veya benzeri” olarak kiralanır ve bir render, filonuzdaki bir aracı değil, katalogdaki bir marka, model ve yılı gösterir. Etikette “veya benzeri” ifadesiyle temsili tek bir model gösterin. Kontuarda belirli bir araç atandığında, bunun yerine o modeli göstermek isterseniz VIN'i ücretsiz olarak katalogdaki araca çözümlenir.

Izgaradaki araçlar neden ölçekli değil?

Çünkü trim her görseli araca göre kırpar ve fit=contain kartı araçla doldurur; böylece kompakt bir araç da tam boy bir SUV de kartını aynı şekilde doldurur. Izgarayı düzenli tutan budur. Boyutu kelimelerle belirtin: sınıf adı, koltuk sayısı ve bagaj sayısı.

Sınıf ızgarasının maliyeti nedir?

Her biri için bir kart ve bir hero görseli olan 4 sınıflık bir filo, ayda 8 araç görseli demektir; her biri her boyutta, gerektiği sıklıkta teslim edilir. Ücretli bir plan aktifken dosyaları CDN’inizde saklarsanız yalnızca onları aldığınız ayda sayılırlar ve ETag ile yeniden kontroller ücretsizdir. Bunun yerine yenilenen imzalı URL’ler sunarsanız aynı görseller, sayfaların açıldığı her ay bir kez sayılır.

Izgarada hangi boya kullanılmalı?

Kartların bir set gibi görünmesi için her sınıfa tek bir hazır renk. 15 hazır renk şunlardır: white, black, gray, silver, blue, red, green, brown, beige, tan, orange, yellow, gold, burgundy, purple; varsayılan ise silver. Herhangi bir hex kodu da aynı fiyata kullanılabilir. Kiracı, otoparkta hangi renk varsa onu alır; kart zaten bunu hiçbir zaman vaat etmemişti.

Bir sınıfın modeli katalogda yoksa ne olur?

Katalogda bulunmayan bir araç, önerilerle birlikte 404 döndürür: her biri kendi id'siyle en yakın katalog araçları. Bunlardan birini kullanın ya da aracı herkese açık istek panosunda talep edin. Katalog açık kaynaklıdır.

Kiralık filo sayfaları için araç görselleri

API'nin belgelenmiş davranışına dayanarak yazılmış bir uygulama kılavuzu; hiçbir müşterinin adını vermez. 30 Eylül 2026 tarihinde yayınlandı.

Sorun: araç değil, sınıf kiralıyorsunuz

Araç kiralayan bir müşteri bir sınıf (kompakt, orta boy SUV, minivan) rezerve eder ve o sınıftan otoparkta hangi araç varsa onunla yola çıkar. Rezervasyon sayfası yine de her sınıf için bir görsele ihtiyaç duyar; yerleşik uygulama da "veya benzeri" ibaresiyle tek bir temsili model göstermektir.

Bu görseller genellikle her birinin bulunabildiği yerden gelir: burada bir basın fotoğrafı, şurada bir bayi fotoğrafı, farklı açılar, farklı arka planlar, kartları farklı biçimde dolduran araçlar. Bu şekilde bir araya getirilmiş bir ızgara derme çatma görünür. Bir filo sayfasının istediği ise tam tersidir: her sınıf aynı şekilde çizilir, böylece karttan karta değişen tek şey araçtır.

Entegrasyon nasıl görünür

Her sınıf için tek bir temsili model; katalog araç kimliği olarak saklanır, "veya benzeri" ifadesi resimde değil, yalnızca etikette yer alır.
Her kart için tek bir istek yapısı: aynı görünüm, kutu, sığdırma, kırpma, dolgu, boya, arka plan ve format.
Sınıf başına en fazla iki görsel: ızgaradaki kart ve sınıf sayfasındaki ana görsel.
Önbelleğe alınır, çünkü ızgara her ziyaretçi için aynıdır: dosyalar CDN'inizde ya da bir kez oluşturulup yeniden kullanılan imzalı URL'ler.

1. Adım: her sınıf için id ile temsili bir model seçin

Her sınıfın hangi modelle satıldığını seçin ve o modelin güncel model yılını bulun. GET /api/v1/vehicles?make=&model= ücretsiz ve herkese açıktır; bir modelin tüm yıllarını, her birini saklayacağınız sabit araç kimliğiyle birlikte listeler. POST /api/v1/images/resolve ise aynısını "2026 toyota rav4" gibi bir ifadeden yapar.

Tek bir model yılının kimliği

# one model's years, each with its vehicle id (free, public)
curl -s "https://carimage.dev/api/v1/vehicles?make=toyota&model=rav4" | jq -c '.data.vehicles[] | select(.year == 2026)'
# {"year":2026,"id":"veh_e5w75c93f6cvk"}

fleet.ts

// One representative model per class: its current model year, by catalog id.
// "or similar" lives in the label; the picture never promises the car on the lot.
export const CLASS_IMAGES = {
  compact:        { vehicle: "veh_fy7r2yvwt4p1v", label: "Toyota Corolla or similar" },    // 2026 Toyota Corolla
  "midsize-suv":  { vehicle: "veh_e5w75c93f6cvk", label: "Toyota RAV4 or similar" },       // 2026 Toyota RAV4
  "fullsize-suv": { vehicle: "veh_9mzh9ejqjye43", label: "Chevrolet Tahoe or similar" },   // 2026 Chevrolet Tahoe
  minivan:        { vehicle: "veh_9jck7rrybf35p", label: "Chrysler Pacifica or similar" }, // 2026 Chrysler Pacifica
};

ID’ler hiç değişmez. Bu nedenle filodaki bir değişiklik yalnızca bu eşlemeyi etkiler: Orta sınıf başka bir modele ya da bir sonraki model yılına geçtiğinde tek bir ID’yi değiştirin. Eşlemeyi okuyan her kart, hero alanı ve e-posta bu değişikliği otomatik olarak izler.

Adım 2: her sınıf için tek bir istek yapısı

9 kamera açısı, katalogdaki her araç için aynı şekilde kadrajlanır; bir ızgarayı hizalı kılan da budur. Kartın geri kalanı, bir kez belirlenen birkaç parametreden ibarettir:

Kartlar için view=side: her araç aynı taban çizgisi üzerinde aynı yöne bakar. Her sol taraf açısının bir -right ikizi vardır (side-right); böylece kartlar düzenin içine bakabilir. Sınıf sayfası, ana görsel açısı olan front-3-4 açısını kullanır.
w=640&h=320&fit=contain: her sınıf için tam olarak 640×320, aracın tamamı görünür. Yanıttaki X-Image-Width ve X-Image-Height tuval boyutunu doğrular.
trim=1&padding=6: aracı sığdırmadan önce araca göre kırpar ve uzun kenarının %6'sını kenar boşluğu olarak bırakır; böylece bir Corolla ile bir Tahoe, kare kaynak çerçevede yüzer gibi durmak yerine kartlarını aynı şekilde doldurur.
background=f4f4f4, kartı ızgaranın kendi gri tonuna sabitler. Şeffaf arka planı korumak ve kartın renginin görünmesini sağlamak için bu parametreyi kullanmayın.
Saklanan dosyalar için format=webp; imzalı URL'lerde ise her tarayıcıya WebP veya PNG sunan format=auto.

Tek bir sınıf için kart ve kapak görseli

# the class card: the same box, view, crop, paint and backdrop for every class
curl --fail-with-body -H "Authorization: Bearer $CAR_IMAGE_API_KEY" \
  "https://carimage.dev/api/v1/images/car?vehicle=veh_e5w75c93f6cvk&view=side&color=white&w=640&h=320&fit=contain&trim=1&padding=6&background=f4f4f4&format=webp" \
  -o midsize-suv-card.webp

# the class page's hero: the three-quarter view, the full width the API delivers
curl --fail-with-body -H "Authorization: Bearer $CAR_IMAGE_API_KEY" \
  "https://carimage.dev/api/v1/images/car?vehicle=veh_e5w75c93f6cvk&view=front-3-4&color=white&w=1024&format=webp" \
  -o midsize-suv-hero.webp

3. Adım: tüm ızgara için tek bir adlandırılmış boya rengi

15 hazır ayar, adlandırılmış boyalardır: white, black, gray, silver, blue, red, green, brown, beige, tan, orange, yellow, gold, burgundy, purple. Varsayılan silver olup grey, gray olarak okunur. Kartların bir set gibi görünmesi için her sınıfa aynı rengi seçin; yukarıda white gösterilmektedir. Her hazır ayar, aynı adlı CSS rengini değil kendi boya örneğini kullanır (red, #b3151b değerindedir) ve hex dahil her boya, hazırlanmış tek bir görünümün yeniden renklendirilmesidir; bu nedenle her boya bir araç görselidir.

Görsel modeli gösterir, sözler ise taahhüdü

Bir render, filonuzdaki bir arabayı değil, katalogdaki bir marka, model ve yılı tasvir eder; kiracı da filoda hangi renk ve donanım varsa onu alır. "veya benzeri" ifadesini, koltuk ve bagaj bilgilerini kartın metninde, görselin yanında tutun.

4. Adım: dosyaları ya da URL'leri önbelleğe alın

Sınıf ızgarası her ziyaretçi için aynıdır, bu yüzden ziyaret başına maliyeti neredeyse sıfır olmalıdır. Buna ulaşmanın iki yolu var:

Dosyaları saklayın. Her kartı ve ana görseli GET /api/v1/images/car ile bir kez alın ve diğer varlıklar gibi kendi CDN'inizden sunun; ücretli bir plan, etkin olduğu sürece ürününüzü sunmak için kendi sunucularınızda kopya tutmanıza izin verir (plan sona erdikten sonraki 30 gün içinde silin ya da bir seti kalıcı olarak saklamak için bir Image Pack satın alın). Her dosyanın ETag değerini saklayın: If-None-Match ile yapılan gecelik yeniden kontrol 304 yanıtı döner ve hiçbir maliyeti yoktur. Yukarıdaki filo için bu, ayın 8 araç görseli eder ve gerektiği kadar yeniden kullanılır.
Ya da imzalı URL'leri bir kez oluşturup yeniden kullanın. POST /api/v1/image-urls çağrı başına en fazla 50 görsel alır ve en fazla 7 gün geçerli olan, anahtar içermeyen URL'ler döndürür. Kullanım sınırı olmayan bir URL, geçerlilik süresi boyunca herkese açık şekilde önbelleğe alınabilir; böylece her ziyaretçi aynı URL'yi yüklediğinde tekrarlanan istekler CDN'den ücretsiz karşılanır. renew: true eklerseniz saklanan bir URL geçerlilik süresi dolduktan sonra da çalışmaya devam eder; bir yenileme, görseli denk geldiği ayda bir kez sayar ve görsel o ay zaten sayılmışsa başka bir şey sayılmaz. Böylece yukarıdaki filo ayda en fazla 8 araç görseli düzeyinde kalır.

URL'leri üreten anahtarı panelde rezervasyon alan adınızla sınırlandırın; başka bir siteye kopyalanan URL 403 döndürür.

Izgaradaki URL'ler, TypeScript SDK ile bir kez oluşturulur

import { CarImageClient, type ImageParams } from "@meterapp/car-image-sdk";
import { CLASS_IMAGES } from "./fleet";

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

// Framed once, for every class.
const card = (vehicle: string): ImageParams => ({
  vehicle, view: "side", color: "white", width: 640, height: 320,
  fit: "contain", trim: true, padding: 6, background: "#f4f4f4", format: "auto",
});
const hero = (vehicle: string): ImageParams => ({ vehicle, view: "front-3-4", color: "white", width: 1024, format: "auto" });

// Every visitor sees the same grid: mint the URLs once and serve the stored ones.
// renew keeps each URL working past its 7-day lifetime, one credit per image
// for each further week in which it is loaded.
const classes = Object.entries(CLASS_IMAGES);
const { data } = await client.createImageUrls(
  classes.flatMap(([, entry]) => [card(entry.vehicle), hero(entry.vehicle)]),
  { ttlSeconds: 604800, renew: true, idempotencyKey: "class-grid-2026-10" }
);
await saveClassImages(
  classes.map(([key], index) => ({ key, card: data[2 * index].url, hero: data[2 * index + 1].url, renewsUntil: data[2 * index].renews_until }))
);

5. Adım: rezervasyon onayı

Onay e-postası rezerve edilen sınıfı gösterir ve e-postalar, kiracı ne zaman fırsat bulursa o zaman açılır. Bu görseli yenilenen bir URL olarak oluşturun: ttl_seconds değerini 7 günlük üst sınıra ayarlayın, renew: true kullanın ve renew_days değerini iade tarihini aşacak şekilde belirleyin. Kimsenin e-postayı açmadığı haftalar hiçbir ücrete yol açmaz ve kiralama bittikten sonra URL yenilenmeyi bırakır. Rezervasyon başına bir Idempotency-Key, yeniden denenen bir gönderimin ikinci bir URL oluşturmak yerine ilk URL'yi tekrar döndürmesini sağlar; URL'yi rezervasyonla birlikte saklamak da sonraki her yeniden gönderimin onu kullanmasına olanak tanır. Kendi yaşam döngüsü e-postalarımız da bu şekilde çalışır; mekanizma ve HTML e-posta hikâyesinde yer alır.

Tek bir rezervasyon onayı için yenilenen URL

// The booking confirmation: opened today, again at the counter, maybe never.
const { data: [classImage] } = await client.createImageUrls(card(booking.classVehicle), {
  ttlSeconds: 604800,
  renew: true,
  // A week past the return date, and no renewals after it (365 days at most).
  renewDays: Math.min(daysUntil(booking.returnDate) + 7, 365),
  // A retried send replays the first URL instead of minting a second one.
  idempotencyKey: `booking:${booking.id}:class`,
});
booking.classImageUrl = classImage.url; // later resends reuse it

CLI, SDK ve MCP

CLI: npx @meterapp/car-image get --vehicle veh_… --view side --width 640 --height 320 --fit contain --trim --padding 6 --out card.webp bir kartı dosyaya yazar; car-image url --batch classes.json --renew toplu olarak URL oluşturur.
SDK: kimlikler için client.vehicles({ make, model }), dosyalar için client.getImage(…), URL'ler için client.createImageUrls(…).
MCP: resolve_vehicle ve create_car_image_urls, bir asistanın "orta boy SUV, RAV4 veya benzeri" ifadesinden bir sınıf kartı taslağı hazırlamasını sağlar. Kurulum adımları MCP sayfasında yer alır.

Sıkça sorulan sorular

Kart, kiracının alacağı arabanın tam kendisini gösterebilir mi?: Hayır, denememeli de. Bir sınıf “veya benzeri” olarak kiralanır ve bir render, filonuzdaki bir aracı değil, katalogdaki bir marka, model ve yılı gösterir. Etikette “veya benzeri” ifadesiyle temsili tek bir model gösterin. Kontuarda belirli bir araç atandığında, bunun yerine o modeli göstermek isterseniz VIN'i ücretsiz olarak katalogdaki araca çözümlenir.
Izgaradaki araçlar neden ölçekli değil?: Çünkü trim her görseli araca göre kırpar ve fit=contain kartı araçla doldurur; böylece kompakt bir araç da tam boy bir SUV de kartını aynı şekilde doldurur. Izgarayı düzenli tutan budur. Boyutu kelimelerle belirtin: sınıf adı, koltuk sayısı ve bagaj sayısı.
Sınıf ızgarasının maliyeti nedir?: Her biri için bir kart ve bir hero görseli olan 4 sınıflık bir filo, ayda 8 araç görseli demektir; her biri her boyutta, gerektiği sıklıkta teslim edilir. Ücretli bir plan aktifken dosyaları CDN’inizde saklarsanız yalnızca onları aldığınız ayda sayılırlar ve ETag ile yeniden kontroller ücretsizdir. Bunun yerine yenilenen imzalı URL’ler sunarsanız aynı görseller, sayfaların açıldığı her ay bir kez sayılır.
Izgarada hangi boya kullanılmalı?: Kartların bir set gibi görünmesi için her sınıfa tek bir hazır renk. 15 hazır renk şunlardır: white, black, gray, silver, blue, red, green, brown, beige, tan, orange, yellow, gold, burgundy, purple; varsayılan ise silver. Herhangi bir hex kodu da aynı fiyata kullanılabilir. Kiracı, otoparkta hangi renk varsa onu alır; kart zaten bunu hiçbir zaman vaat etmemişti.
Bir sınıfın modeli katalogda yoksa ne olur?: Katalogda bulunmayan bir araç, önerilerle birlikte 404 döndürür: her biri kendi id'siyle en yakın katalog araçları. Bunlardan birini kullanın ya da aracı herkese açık istek panosunda talep edin. Katalog açık kaynaklıdır.

Okumaya devam edin

Müşteri hikâyesi · Geliştirici araçlarıHiç bozulmayan imzalı URL'lerle e-postalara araç görselleri nasıl eklenirKendi yaşam döngüsü e-postalarımız, her müşterinin ilk render'ını birebir, bir yıl boyunca kendini yenileyen canlı bir imzalı URL olarak içerir. Bunun nasıl çalıştığını ve nasıl uygulayabileceğinizi burada anlatıyoruz.