Claude Prompt Caching Maliyet Analizi ve Basit Hesaplama

Prompt caching maliyetleri: Tasarruf etmeden önceki maliyet

Prompt caching, Claude'un isteminizin başlangıç kısmını her çağrıda yeniden okumak yerine tekrar kullanmasını sağlar; bu kararın tüm maliyeti, modelin temel girdi fiyatı üzerindeki iki çarpan ile belirlenir. Ağustos 2026 itibarıyla, 5 dakikalık yaşam süresi için önbelleğe yazma işlemi temel girdi fiyatının 1.25 katı, 1 saatlik yaşam süresi için ise 2 katıdır. Önbellekten okuma maliyeti ise 0.1 katıdır. Bu çarpanlar tüm model listesi için geçerlidir, bu nedenle token başına fiyat değiştiğinde aşağıdaki başa baş noktası değişmez.

Bu işlem, şimdi ödenen bir ek ücret ile daha sonra elde edilecek bir indirim arasındaki takastır. Bir öneki depolamak için bir kez fazladan ödeme yaparsınız. Tam olarak aynı baytlarla başlayan her sonraki istek, o kısım için normal girdi fiyatının onda birini öder. Yaşam süresi boyunca asla yeniden kullanılmayan bir önek, size yüzde 25 oranında gereksiz bir maliyet yükler.

Başa baş noktası, tek satırlık cebir

Ön ekin (prefix) önbelleğe alınmadığı durumdaki temel girdi maliyetine B diyelim. Önbellekleme olmadan N adet istek, N çarpı B maliyetine denk gelir. 5 dakikalık önbellek kullanıldığında, ilk istek ön eki 1.25B maliyetle yazar ve diğer N eksi 1 istek ise 0.1B maliyetle okur. İki tarafı birbirine eşitlediğinizde 0.9N = 1.15 sonucuna ulaşırsınız, yani N = 1.28 olur. İkinci istek, önbellekleme yapmamaya kıyasla şimdiden daha ucuzdur.

Aynı işlemi 1 saatlik önbelleğin 2 katı yazma maliyetiyle tekrarladığınızda 0.9N = 1.9 sonucunu, yani N = 2.11 değerini elde edersiniz. Uzun süreli önbelleğin başa baş noktasına ulaşması için iki okuma gerekir; varsayılan seçenek olmamasının nedeni budur.

Aşağıdaki tablo, Ağustos 2026 itibarıyla temel girdi ücreti milyon token başına 5 dolar olan Claude Opus 5 üzerinde 20.000 tokenlık bir ön ek için bu maliyetleri fiyatlandırmaktadır. Milyon token başına 3 dolarlık bir model için her rakamı 0.6 ile çarpın. Eğrinin şekli değişmeyecektir.

[
  {
    "requests": 1,
    "uncached_usd": "0.10",
    "cached_5m_usd": "0.125",
    "cached_1h_usd": "0.20"
  },
  {
    "requests": 2,
    "uncached_usd": "0.20",
    "cached_5m_usd": "0.135",
    "cached_1h_usd": "0.21"
  },
  {
    "requests": 3,
    "uncached_usd": "0.30",
    "cached_5m_usd": "0.145",
    "cached_1h_usd": "0.22"
  },
  {
    "requests": 5,
    "uncached_usd": "0.50",
    "cached_5m_usd": "0.165",
    "cached_1h_usd": "0.24"
  },
  {
    "requests": 10,
    "uncached_usd": "1.00",
    "cached_5m_usd": "0.215",
    "cached_1h_usd": "0.29"
  },
  {
    "requests": 20,
    "uncached_usd": "2.00",
    "cached_5m_usd": "0.315",
    "cached_1h_usd": "0.39"
  }
]

Tek başına yapılan bir istek, önbelleksiz $0.10, önbellekli ise $0.125 maliyete sahiptir; bu nedenle tek seferlik bir istemi önbelleğe almak doğrudan zarardır. İkinci istekte 5 dakikalık önbellek $0.135 maliyete düşerken, önbelleksiz maliyet $0.20 seviyesindedir. 1 saatlik önbellek bu noktada hala geridedir; $0.21 maliyeti, aynı $0.20 maliyetine karşı henüz geçememiştir ve önbelleksiz çizgiyi ancak üçüncü istekte geçer: $0.22 maliyeti, $0.30 maliyetine karşı. 20 istek sonunda aradaki fark, $2.00 maliyetine karşı $0.315 şeklindedir.

Önbellek isabeti (cache hit) aynı zamanda girişi yeniler; yayınlanan fiyat tablosunda o sütunun "önbellek isabetleri ve yenilemeler" olarak adlandırılmasının nedeni budur. Bu nedenle yoğun bir uç nokta, 5 dakikalık bir girişi okuma fiyatları üzerinden süresiz olarak canlı tutar; 1 saatlik ömür ise yalnızca trafiğinizde gerçek boşluklar olduğunda 2 katı yazma maliyetini haklı çıkarır.

Düşük isabet oranının maliyeti

Gerçek trafik ıskalamalara neden olur. Önbelleği ıskalayan ancak yine de bir kesme noktası taşıyan bir istek, yazma işlemi olarak ücretlendirilir; bu nedenle bunu modellemenin en doğru yolu, maliyeti isabet oranının bir fonksiyonu olarak ele almaktır. Aşağıdaki grafik, her biri aynı 20,000 token'lık öneki taşıyan 1,000 istek için bu durumu göstermektedir.

[
  {
    "hit_rate_percent": 0,
    "cost_5m_usd": "125.00",
    "cost_1h_usd": "200.00",
    "uncached_usd": "100.00"
  },
  {
    "hit_rate_percent": 25,
    "cost_5m_usd": "96.25",
    "cost_1h_usd": "152.50",
    "uncached_usd": "100.00"
  },
  {
    "hit_rate_percent": 50,
    "cost_5m_usd": "67.50",
    "cost_1h_usd": "105.00",
    "uncached_usd": "100.00"
  },
  {
    "hit_rate_percent": 75,
    "cost_5m_usd": "38.75",
    "cost_1h_usd": "57.50",
    "uncached_usd": "100.00"
  },
  {
    "hit_rate_percent": 90,
    "cost_5m_usd": "21.50",
    "cost_1h_usd": "29.00",
    "uncached_usd": "100.00"
  },
  {
    "hit_rate_percent": 95,
    "cost_5m_usd": "15.75",
    "cost_1h_usd": "19.50",
    "uncached_usd": "100.00"
  },
  {
    "hit_rate_percent": 99,
    "cost_5m_usd": "11.15",
    "cost_1h_usd": "11.90",
    "uncached_usd": "100.00"
  }
]

Yüzde 0 isabet oranında, $100.00 yerine $125.00 ödersiniz ve 1 saatlik önbellek faturayı $200.00 tutarına çıkararak ikiye katlar. 1.25 eksi 1.15h eşittir 1 denklemini çözdüğünüzde, 5 dakikalık önbelleğin yaklaşık yüzde 22'lik bir isabet oranında tasarruf sağlamaya başladığını görürsünüz; bu yüzden yüzde 25'lik oran halihazırda $96.25 değerini göstermektedir. Aynı hesaplama 2 kat yazma işlemi için yapıldığında 1 saatlik önbellek için yaklaşık yüzde 53 sonucu çıkar; dolayısıyla yüzde 50'lik bir isabet oranı, önbelleksiz hattın üzerinde kalarak hala $105.00 maliyetine neden olur. Yüzde 90'da ise her iki değer $21.50 ve $29.00 noktalarına iner. Yüzde 99'da kısa süreli önbellek, önbelleksiz fiyatın onda biri olan taban değerine yakın bir seviye olan $11.15 değerine ulaşır.

İsabet oranı, ölçümlemeniz gereken temel değerdir; çünkü önek boyutu sabitlendikten sonra kontrol edebildiğiniz tek girdi budur.

Hangi önekler kesme noktası (breakpoint) için uygundur

Bir istek dört adede kadar önbellek kesme noktası taşıyabilir, bu nedenle hangi blokların bir kesme noktasını hak ettiği sorusu önem kazanır. Adaylar, çağrılar arasında bayt düzeyinde aynı kalan ve dikkate değer büyüklükte olan bloklardır. Aşağıdaki tablo, 5 dakikalık önbellekte yüzde 90 isabet oranıyla 1.000 istek üzerinden dört yaygın şekli fiyatlandırmaktadır.

[
  {
    "label": "System prompt",
    "prefix_size_tokens": "2,000",
    "uncached_usd": "10.00",
    "cached_usd": "2.15",
    "saved_usd": "7.85"
  },
  {
    "label": "System plus tools",
    "prefix_size_tokens": "8,000",
    "uncached_usd": "40.00",
    "cached_usd": "8.60",
    "saved_usd": "31.40"
  },
  {
    "label": "Policy document",
    "prefix_size_tokens": "25,000",
    "uncached_usd": "125.00",
    "cached_usd": "26.88",
    "saved_usd": "98.12"
  },
  {
    "label": "Codebase context",
    "prefix_size_tokens": "120,000",
    "uncached_usd": "600.00",
    "cached_usd": "129.00",
    "saved_usd": "471.00"
  }
]

Yalın bir 2,000 token'lık sistem istemi (prompt), önbelleksiz 10.00 maliyete kıyasla 1.000 istek başına $7.85 tasarruf sağlar. Yüksek hacimlerde bu gerçek bir paradır ancak önbelleğe almayı ilginç kılan asıl nokta bu değildir. Araç tanımlarını eklediğinizde 8,000 token seviyesine ulaşırsınız ve $31.40 tasarruf edersiniz. Her isteğin soru sorduğu 25,000 token'lık bir politika belgesi $98.12 tasarruf sağlar. Son satır mimariyi değiştiren kısımdır: 120,000 token'lık kod tabanı veya transkript bağlamı, önbelleksiz durumda $600.00, önbellekli durumda ise $129.00 maliyete sahiptir; bu da $471.00 tutarında bir tasarruf demektir.

Tasarruflar önek boyutu ve isabet oranı ile ölçeklenir, başka hiçbir şeyle değil. Bu durum, bir istemin içine ne koymanın değerli olduğunu değiştirir: bir milyon Claude token'ının gerçek maliyeti, birden fazla kez gönderdiğiniz her şey için liste fiyatının onda birine düşer.

Aylık faturada nasıl görünür

Aşağıdaki tablo, yukarıdaki 8,000 belirteç önekini, bir sistem istemini ve araç tanımlarını yüzde 90 isabet oranıyla alır ve bunu aylık istek hacimlerine göre ölçeklendirir.

[
  {
    "label": "10k requests",
    "uncached_usd": "400.00",
    "cached_usd": "86.00",
    "saved_usd": "314.00"
  },
  {
    "label": "100k requests",
    "uncached_usd": "4,000.00",
    "cached_usd": "860.00",
    "saved_usd": "3,140.00"
  },
  {
    "label": "1M requests",
    "uncached_usd": "40,000.00",
    "cached_usd": "8,600.00",
    "saved_usd": "31,400.00"
  }
]

Ayda 10.000 istekte tasarruf $314.00 tutarındadır; bu, $400.00 ile $86.00 arasındaki farktır. 100.000 istekte bu tutar $3,140.00 olur. Bir milyon istekte önbelleğe alınmamış girdi faturası $40,000.00 tutarındadır ve önbelleğe alma bunun $31,400.00 kadarını ortadan kaldırır. Bunlar yalnızca girdi belirteçleridir. Çıktı ayrı olarak fiyatlandırılır ve önbelleğe almanın çıktı üzerinde bir etkisi yoktur; birine yüzde 90 fatura indirimi sözü vermeden önce bunu hatırlamakta fayda vardır. Önbelleğe alma, bir yapay zeka temsilcisinin faturasını VPS üzerinde kontrol altında tutma konusundaki daha geniş alışkanlıklarla birlikte değerlendirilmelidir.

Önbelleğin çalıştığını doğrulama

Tasarıma güvenmeyin. Yanıt üzerindeki kullanım bloğunu okuyun. Her Messages API (uygulama programlama arayüzü) yanıtı, yazdığı önbelleğe alınmış token'ları, okuduğu önbelleğe alınmış token'ları ve işlemek zorunda kaldığı yeni token'ları raporlar.

from anthropic import Anthropic

client = Anthropic()

resp = client.messages.create(
    model="claude-opus-5",
    max_tokens=512,
    system=[
        {
            "type": "text",
            "text": POLICY_DOCUMENT,
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[{"role": "user", "content": question}],
)

u = resp.usage
print("write:", u.cache_creation_input_tokens)
print("read: ", u.cache_read_input_tokens)
print("fresh:", u.input_tokens)

Aynı belge ve farklı bir soru ile iki kez çalıştırın. İlk çağrı sıfır olmayan bir cache_creation_input_tokens ve sıfır bir cache_read_input_tokens raporlar. İkinci çağrı bunu tersine çevirir, çünkü önek bulunmuştur. input_tokens yalnızca son kesme noktasından sonraki token'ları sayar, bu nedenle sağlıklı bir ikinci çağrıda bu sayı küçüktür; genellikle sadece yeni kullanıcı mesajından ibarettir.

Aynı kontrolü kabuk üzerinden, request.json dosyasına kaydettiğiniz bir istek gövdesine karşı yapın:

curl -s https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d @request.json | jq '.usage'

Sağlıklı bir ikinci çağrı buna benzer bir çıktı verir:

{
  "input_tokens": 42,
  "cache_creation_input_tokens": 0,
  "cache_read_input_tokens": 20143,
  "output_tokens": 187
}

Tek bir satır size gerçeği söyler. Eğer cache_read_input_tokens çağrılar boyunca 0'da kalıyorsa, her seferinde 1.25x yazma maliyetini ödüyor ve karşılığında hiçbir şey almıyorsunuz demektir.

1 saatlik yaşam süresi için, kesme noktası bir yaşam süresi (TTL) taşır:

{
  "type": "text",
  "text": "your stable prefix",
  "cache_control": {"type": "ephemeral", "ttl": "1h"}
}

Ayrıca otomatik önbelleğe alma da mevcuttur: isteğin en üst seviyesinde tek bir cache_control alanı; bu alandan sonra API, konuşma büyüdükçe kesme noktalarını yönetir. Bu, dört kesme noktası yuvanızdan birini tüketir. İşe buradan başlayın. Kesme noktasının tam olarak nerede duracağına karar vermeniz gerektiğinde açık kesme noktalarına geçin.

İsabet oranını düşüren sıralama kuralı

Önbellek, isteğin başından itibaren bayt bazında bir önek eşleştirmesi yapar ve istek sabit bir sırada birleştirilir: araçlar, ardından sistem, en son mesajlar. Herhangi bir seviyedeki değişiklik, o seviyeyi ve ondan sonra gelen her şeyi geçersiz kılar. Bir araç açıklamasını düzenlediğinizde, sistem istemi ve tüm mesaj geçmişi, onlara dokunmamış olsanız dahi geçersiz kalır.

Bu durum, istisnası olmayan tek bir kural doğurur: Çağrılar arasında değişen her şey, değişmeyen her şeyden sonra gelmelidir.

Buna genellikle zaman damgaları neden olur. Bir sistem isteminin en üstünde yer alan Current time: 2026-08-03T14:07:11Z satırı, yüzde 0 isabet oranını garanti eder; çünkü önek özeti (prefix hash) her çağrıda farklıdır ve önceki hiçbir girdi bununla eşleşemez. Bu veriyi kullanıcı mesajının sonuna taşıyın. Bir oturum tanımlayıcısı veya istek başına oluşturulan bir nonce (tek kullanımlık sayı) aynı şekilde çalışmayı bozar ve aynı çözümle düzeltilir. İstek başına farklılık gösteren getirilen belgeler de önbelleğe alınmış bloğun sonrasına yerleştirilmelidir; aksi takdirde, sabit tüm belirteçleri (token) hareketli bir sınırın arkasına iterler.

İkinci hata, kesme noktasını (breakpoint) değişen bloğa koymaktır. Önbellek yazma işlemleri kesme noktasında gerçekleşir; bu nedenle, eğer o blok her seferinde farklıysa, hiçbir sabit veri depolanamaz ve geriye dönük arama, yalnızca önceki isteklerin kendi hareketli kesme noktalarında yazdığı girdileri bulur. cache_control işaretini, içeriği istekler arasında aynı olan son bloğa yerleştirin.

Üçüncüsü, istem içeriği olarak düşünmediğiniz bir parametre değişikliğidir. Farklı bir modelin farklı bir önbelleği vardır. Araç seçimini değiştirmek, sistem seviyesinden itibaren her şeyi geçersiz kılar. Bir araç eklemek veya çıkarmak her şeyi geçersiz kılar.

Minimum önek ve sessiz işlem yapmama durumu

Modelin minimum değerinden daha kısa bir önek önbelleğe alınmaz ve bu durum size bildirilmez. Hata veya uyarı mesajı oluşmaz. İstek başarıyla tamamlanır ve her iki sayaç da 0 değerini gösterir. Ağustos 2026 itibarıyla yayınlanan minimum değerler şöyledir:

• Claude Opus 5 ve Claude Fable 5 üzerinde 512 token
• Claude Sonnet 5 ve Claude Opus 4.8 üzerinde 1.024 token
• Claude Haiku 4.5 üzerinde 4.096 token

Önbelleğe alındığını düşündüğünüz bir istekte her iki sayaç da 0 değerini gösteriyorsa, başka bir işlem yapmadan önce önek uzunluğunu kontrol edin. En ucuz modelin, önbellekleme iş yükleri için otomatik olarak en ekonomik seçenek olmamasının nedeni de budur. Haiku 4.5, önbelleklemenin devreye girmesi için Opus 5'ten sekiz kat daha uzun bir öneke ihtiyaç duyar; bu nedenle 2.000 tokenlık bir sistem istemi, bir modelde önbelleğe alınırken diğerinde sessizce göz ardı edilir.

Claude Code'un önbellekleme yaptığı yerler ve yapamadığı durumlar

Claude Code kendi önekini (prefix) önbelleğe alır. Sistem istemi ve araç tanımları her isteğin başında yer alır ve değişmez; bu nedenle bir kez yazılır ve oturumun geri kalanı boyunca tekrar okunur. Uzun bir oturumun her adımındaki maliyetin, bağlam boyutunun düşündürdüğünden çok daha düşük olmasının nedeni budur ve bu durum Claude Code'un token kullanımını nasıl raporladığı bölümünde açıklanan sayaçlarda görülür.

Yardımcı olamadığı durum ise bağlamın başlangıcına yakın yapılan düzenlemelerdir. Konuşma geçmişi yalnızca ekleme yapılabilir (append-only) yapıdadır, bu nedenle normal yeni adımlar zaten önbelleğe alınmış bir öneki genişletir. Oturumun başında okunan bir dosyayı düzenlemek, bu önekin ortasındaki içeriği değiştirir ve değişiklikten sonraki her token'ın yeniden yazılması gerekir. Uzun bir boşluk süresi de aynı etkiyi yaratır; çünkü girişin süresi dolar ve bir sonraki adım tam yazma maliyetine neden olur. Bunların hiçbiri bir hata değildir. Her ikisi de önek kuralının tam olarak belirtildiği şekilde çalışmasından kaynaklanır.

Eğer kendi istemcinizi yazıyorsanız, düzeni sonradan uyarlamak yerine ilk istekten itibaren uygulayın: çağrıyı bir VPS üzerinde ilk Claude API uygulaması örneğinde olduğu gibi, sabit bloklar başta ve değişken olanlar sonda olacak şekilde oluşturun.

Hata modları ve karşılaşacağınız durumlar

Her çağrı bir yazma işlemidir. cache_creation_input_tokens her istekte sıfırdan farklıdır, cache_read_input_tokens ise 0 kalır. Kesme noktasında veya öncesinde bir şey çağrılar arasında değişmektedir. Birleştirilmiş önekinizin ilk 200 karakterini art arda iki istekte yazdırın ve gözle karşılaştırın.

Her iki sayaç da 0. Önek, model minimumunun altındadır veya cache_control alanı API'ye hiç ulaşmamıştır. Önce önek belirteçlerini (token) sayın, ardından gerçekten gönderdiğiniz istek gövdesini günlüğe kaydedin.

Okumalar çalışıyor, sonra duruyor. Bir dizi isabet, ardından bir yazma ve tekrar isabetler. İstekler arasındaki boşluk, yaşam süresinden (lifetime) daha uzundu. Yazma işlemini kabul edin veya isabet oranınızın yüzde 53'ü geçtiğini doğruladıktan sonra 1 saatlik TTL değerine geçin.

Dağıtım (deploy) sonrası isabet oranı düşüyor. Bir araç açıklaması düzenlendi veya bir model değiştirildi. Her ikisi de tüm öneki geçersiz kılar. İstemi etkileyen her dağıtımdan sonra bir tur maliyetli yazma işlemi bekleyin.

Önbelleği etkinleştirdikten sonra fatura arttı. İsabet oranınız başa baş noktasının altındadır. 5 dakikalık önbellekte yaklaşık yüzde 22'nin altında, öneki önbelleksiz göndermek daha ucuzdur; 1 saatlik önbellekte ise yaklaşık yüzde 53'ün altında aynı durum geçerlidir.

FAQ

Bir istemin, önbelleğe almanın maliyetini karşılaması için kaç kez yeniden kullanılması gerekir?

5 dakikalık önbellekte bir kez yeterlidir. Yazma işlemi temel girdi maliyetinin 1.25 katı, okuma işlemi ise 0.1 katıdır; bu durumda N adet önbelleksiz istek N maliyetine sahipken, N adet önbellekli istek 1.25 artı N eksi 1'in 0.1 katı maliyetine sahiptir. İki değer N = 1.28 noktasında kesişir, dolayısıyla ikinci istekte maliyet avantajı sağlanmış olur. 1 saatlik önbellek ise 2 kat yazma maliyetiyle N = 2.11 noktasında kesişir, bu nedenle iki okuma gerektirir.

Neden cache_read_input_tokens değeri her zaman sıfır?

Öncelikle önek uzunluğunu kontrol edin: Ağustos 2026 itibarıyla Claude Opus 5 için 512 token ve Claude Haiku 4.5 için 4.096 token olan model minimumunun altındaki değerlerde önbelleğe alma sessizce atlanır ve her iki sayaç da 0 değerini gösterir. Eğer önek yeterince uzunsa, sistem istemindeki zaman damgası veya oturum tanımlayıcısı gibi çağrılar arasında değişen ve kesme noktasında veya öncesinde yer alan içerikleri inceleyin. Sayaçlar çalışırken durduysa, istekler arasındaki süre önbellek ömründen daha uzun sürmüş demektir.

İstem önbelleğe alma, Claude'un yanıtlarını değiştirir mi?

Hayır. Önbellek, daha önce gönderdiğiniz token'ların işlenmiş halini saklar ve model her iki durumda da aynı istemi görür. Bu bir faturalandırma ve gecikme süresi özelliğidir, davranış değişikliği değildir. Bu durum, değerlendirmelerinizi yeniden çalıştırmanıza gerek kalmadan çalışan bir istem üzerinde önbelleğe almayı etkinleştirebileceğiniz anlamına gelir.

1 saatlik önbellek için ödeme yapmalı mıyım?

Yalnızca trafiğinizde 5 dakikadan uzun boşluklar olduğunda ve isabet oranınız yine de yaklaşık yüzde 53 seviyesini koruyacaksa ödeme yapmalısınız. 2 kat yazma maliyeti, isabet sağlanamadığında 1.25 kat yazma maliyetine göre iki kat daha fazla dezavantaj yaratır. 5 dakikalık giriş her isabette yenilenir; bu sayede düzenli trafik, daha uzun ömür için ekstra ödeme yapmadan okuma fiyatlarıyla önbelleği canlı tutar.