Claude prompt caching maliyet hesaplama rehberi

Prompt caching maliyetleri: Tasarruf öncesi maliyetler

Prompt caching, Claude'un isteminizin ön kısmını her çağrıda yeniden okumak yerine tekrar kullanmasına olanak tanır; bu kararın tüm maliyeti, modelinizin temel girdi fiyatı üzerindeki iki çarpan ile belirlenir. Ağustos 2026 itibarıyla, 5 dakikalık yaşam süresi için bir önbellek yazma işlemi temel girdinin 1.25 katı, 1 saatlik yaşam süresi için ise 2 katı maliyete sahiptir. Önbellek okuma maliyeti ise 0.1 katıdır. Bu çarpanlar tüm model listesi genelinde 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 edilen bir indirim arasındaki takastır. Bir öneki depolamak için bir kez fazladan ödeme yaparsınız. Tam olarak aynı baytlarla başlayan sonraki her istek, o kısım için normal girdi fiyatının onda birini öder. Yaşam süresi içinde asla yeniden kullanılmayan bir önek, size yüzde 25 fazladan maliyete neden olur ve hiçbir fayda sağlamaz.

Cebirsel olarak başa baş noktası

Önek için temel girdi maliyetini, önbelleksiz gönderim durumunda B olarak adlandıralım. Önbellekleme olmadan N adet istek, N çarpı B maliyetine denk gelir. 5 dakikalık önbellek ile ilk istek öneki 1.25B maliyetle yazar, diğer N eksi 1 istek ise 0.1B maliyetle okur. İkisini birbirine eşitlediğinizde 0.9N = 1.15 sonucuna ulaşırsınız, bu da N = 1.28 eder. İkinci istek, önbellekleme yapmamaktan zaten daha ucuzdur.

Aynı işlemi 1 saatlik önbelleğin 2 katı yazma maliyetiyle tekrarladığınızda 0.9N = 1.9 sonucunu elde edersiniz, bu da N = 2.11 eder. Uzun süreli önbellek, başa baş noktasına ulaşmak için iki okuma gerektirir; varsayılan tercih olmamasının nedeni budur.

Aşağıdaki grafik, Ağustos 2026 itibarıyla temel girdi ücreti milyon token başına 5 dolar olan Claude Opus 5 üzerindeki 20,000 tokenlik bir önek için fiyatlandırmayı göstermektedir. Milyon token başına 3 dolarlık bir model için her rakamı 0.6 ile ölçeklendirin. 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 bir istek, önbelleksiz $0.10, önbellekli ise $0.125 maliyetindedir; bu nedenle tek seferlik bir istemi önbelleğe almak tamamen zarardır. İkinci istekte 5 dakikalık önbellek $0.135 maliyetine karşılık $0.20 maliyetindedir. 1 saatlik önbellek bu noktada hala geridedir; $0.21 maliyetine karşılık aynı $0.20 maliyeti söz konusudur ve önbelleksiz çizgiyi ancak üçüncü istekte geçer: $0.22 maliyetine karşılık $0.30. 20 istek sonunda fark, $2.00 maliyetine karşılık $0.315 şeklindedir.

Bir önbellek isabeti (cache hit) aynı zamanda girdiyi tazeler; yayınlanan fiyat tablosunda o sütunun "önbellek isabetleri ve tazelemeler" olarak adlandırılmasının nedeni budur. Bu nedenle yoğun bir uç nokta, 5 dakikalık bir girdiyi okuma fiyatları üzerinden süresiz olarak canlı tutar; 1 saatlik yaşam süresi ise yalnızca trafiğinizde gerçek boşluklar olduğunda 2 katı yazma maliyetini hak eder.

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

Gerçek trafik isabet etmez. Ö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 bunu 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 kadar ikiye katlar. 1.25 eksi 1.15h = 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; bu nedenle yüzde 50'lik bir isabet oranı, önbelleksiz hattın üzerinde kalarak $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.

Ölçümlenmesi gereken değer isabet oranıdır, çünkü önek boyutu sabitlendikten sonra kontrol edebileceğiniz tek girdi budur.

Hangi önekler kesme noktasına değer

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 alınacak kadar büyük 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"
  }
]

Sade bir 2,000 token'lık sistem istemi, önbelleğe alınmamış 10.00 maliyete kıyasla 1.000 istek başına $7.85 tasarruf sağlar. Yüksek hacimlerde gerçek bir maddi kazançtır ancak önbelleğe almayı ilginç kılan asıl şey bu değildir. Araç tanımlarını eklediğinizde 8,000 token'a ve $31.40 tasarrufa ulaşırsınız. 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ı, önbelleğe alınmadığında 600.00, önbelleğe alındığında ise 129.00 maliyete sahiptir; bu da $471.00 tutarında bir tasarruf anlamına gelir.

Tasarruflar önek boyutu ve isabet oranı ile ölçeklenir, başka hiçbir şeyle değil. Bu durum, bir isteme neyin konulmaya değer 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 faturaya yansıması

Aşağıdaki tablo, yukarıdaki 8,000 belirteç önekini, bir sistem istemini ve araç tanımlarını yüzde 90 isabet oranıyla ele alır ve bunları 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"
  }
]

Aylık 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 seviyesindedir ve önbellekleme bunun $31,400.00 kadarını ortadan kaldırır. Bunlar yalnızca girdi belirteçleridir. Çıktı ayrı olarak fiyatlandırılır ve önbellekleme çıktı üzerinde bir etkiye sahip değildir; birine yüzde 90 fatura indirimi sözü vermeden önce bunu hatırlamakta fayda vardır. Önbellekleme, bir yapay zeka temsilcisinin maliyetini 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 değer küçüktür; genellikle sadece yeni kullanıcı mesajından oluşur. Her iki çağrı da ücretlendirilir, çünkü Claude API'nin ücretsiz bir katmanı yoktur, ancak yukarıda fiyatlandırılan 20.000 token'lık önek için bu ikili yaklaşık on dört sente mal olur.

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

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ı şuna 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 ücreti ö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. Buradan başlayın. Sınırı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 bayt bir önek eşleşmesi yapar ve istek sabit bir sırada oluşturulur: 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, siz onlara dokunmamış olsanız bile bununla birlikte geçersiz hale gelir.

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 karması her çağrıda farklıdır ve hiçbir önceki girdi onunla eşleşemez. Bunu kullanıcı mesajının sonuna taşıyın. Bir oturum tanımlayıcısı veya istek başına oluşturulan bir nonce değeri de 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 arkasına yerleştirilmelidir; aksi takdirde, sabit olan her belirteci hareketli bir sınırın arkasına iterler.

İkinci neden, kesme noktasını 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. Herhangi bir hata veya uyarı 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 şey 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 token'lık bir sistem istemi, bir modelde önbelleğe alınırken diğerinde sessizce göz ardı edilir.

Claude Code'un sizin için ö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 bir turundaki 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ığı kısmında açıklanan sayaçlarda görülür.

Size yardımcı olamadığı durum, bağlamın başlangıcına yakın bir düzenlemedir. Konuşma geçmişi yalnızca ekleme yapılabilir (append-only) yapıdadır, bu nedenle normal yeni turlar 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 tur tam yazma maliyetine tabi 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 bunun yerine 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 bloklar sonda olacak şekilde oluşturun.

Hata modları ve karşılaşacaklarınız

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 çağrılar arasında bir şey değişmektedir. Birleştirilmiş önekinizin ilk 200 karakterini art arda gelen 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 ancak 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ğe almayı etkinleştirdikten sonra fatura yükseldi. İ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 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. Bir yazma işlemi temel girdi maliyetinin 1.25 katına, bir okuma işlemi ise 0.1 katına mal olur; bu durumda N adet önbelleksiz istek N maliyetine, N adet önbellekli istek ise 1.25 artı 0.1 çarpı (N eksi 1) maliyetine denk gelir. İ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 ve 4 için 512 token, Claude Haiku 4.5 için 4,096 token olan model minimumunun altındaki değerlerde önbelleğe alma işlemi 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ünü aşmış 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 yaklaşık yüzde 53 seviyesinin üzerinde kalacaksa tercih edilmelidir. 2 kat yazma maliyeti, önbellek isabeti gerçekleşmediğinde 1.25 kat yazma maliyetine göre iki kat daha fazla dezavantaj yaratır. 5 dakikalık giriş her isabetle yenilenir; bu nedenle düzenli trafik, daha uzun ömür için ekstra ödeme yapmadan okuma fiyatlarıyla önbelleğin canlı kalmasını sağlar.