Prompt Caching Claude: Kapan Mulai Hemat?

Biaya prompt caching sebelum memberikan penghematan

Prompt caching memungkinkan Claude menggunakan kembali bagian awal prompt tanpa membacanya lagi pada setiap panggilan. Seluruh keputusan ditentukan oleh dua pengali terhadap harga input dasar model. Per Agustus 2026, penulisan cache dikenai biaya 1.25x input dasar untuk masa berlaku 5 menit, atau 2x untuk masa berlaku 1 jam. Pembacaan cache dikenai biaya 0.1x. Pengali tersebut berlaku pada seluruh daftar model, sehingga titik impas di bawah ini tidak berubah ketika harga per token berubah.

Pertukarannya adalah biaya tambahan sekarang untuk mendapatkan diskon kemudian. Anda membayar biaya tambahan satu kali untuk menyimpan suatu prefix. Setiap permintaan berikutnya yang dimulai dengan byte yang sama persis kemudian hanya membayar sepersepuluh dari harga input normal untuk bagian tersebut. Prefix yang tidak pernah digunakan kembali selama masa berlakunya membuat Anda membayar biaya tambahan 25 persen tanpa manfaat.

Titik impas, dalam satu baris aljabar

Misalkan B adalah biaya input dasar untuk prefix jika Anda mengirimkannya tanpa cache. Tanpa caching, N request berbiaya N kali B. Dengan cache 5 menit, request pertama menulis prefix dengan biaya 1.25B dan N dikurangi 1 request lainnya membacanya dengan biaya 0.1B. Samakan keduanya dan Anda mendapatkan 0.9N = 1.15, sehingga N = 1.28. Request kedua sudah lebih murah daripada tidak menggunakan caching sama sekali.

Ulangi perhitungan tersebut dengan penulisan 2x pada cache 1 jam dan Anda mendapatkan 0.9N = 1.9, sehingga N = 2.11. Cache dengan durasi panjang memerlukan dua pembacaan sebelum mencapai titik impas. Karena itu, cache ini bukan pilihan default.

Diagram di bawah menghitung biaya ini untuk prefix 20,000 token pada Claude Opus 5, yang tarif input dasarnya adalah $5 per juta token per Agustus 2026. Kalikan setiap angka dengan 0.6 untuk model dengan tarif $3 per juta token. Bentuk kurvanya tidak berubah.

[
  {
    "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"
  }
]

Satu request saja berbiaya $0.10 tanpa cache dan $0.125 dengan cache. Karena itu, caching pada prompt yang hanya digunakan sekali merupakan kerugian murni. Pada request kedua, cache 5 menit berbiaya $0.135, dibandingkan $0.20. Pada titik tersebut, cache 1 jam masih lebih mahal, yaitu $0.21, dibandingkan $0.20 yang sama. Cache tersebut baru lebih murah daripada penggunaan tanpa cache pada request ketiga: $0.22, dibandingkan $0.30. Pada 20 request, selisihnya adalah $2.00 tanpa cache, dibandingkan $0.315 dengan cache.

Cache hit juga memperbarui masa berlaku entri. Karena itu, tabel harga yang dipublikasikan menamai kolom tersebut cache hits and refreshes. Endpoint yang sibuk dapat mempertahankan entri 5 menit tetap aktif tanpa batas dengan harga pembacaan. Sementara itu, masa berlaku 1 jam hanya menguntungkan jika lalu lintas Anda memiliki jeda yang nyata, sehingga penulisan 2x dapat terhindarkan lebih sering.

Biaya akibat rasio cache hit yang rendah

Trafik nyata menghasilkan cache miss. Request yang mengalami cache miss tetapi tetap membawa breakpoint dikenai biaya sebagai operasi write. Karena itu, cara yang tepat untuk memodelkannya adalah menyatakan biaya sebagai fungsi dari rasio cache hit. Diagram di bawah menunjukkan hal tersebut untuk 1,000 request, yang masing-masing membawa prefix dengan 20,000 token.

[
  {
    "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"
  }
]

Pada rasio cache hit 0 persen, biaya yang dibayar adalah $125.00, bukan $100.00, dan cache 1 hour menggandakan tagihan menjadi $200.00. Dengan menyelesaikan persamaan 1.25 minus 1.15h = 1, cache 5 minute mulai menghemat biaya pada rasio cache hit sekitar 22 persen. Karena itu, rasio 25 persen sudah menghasilkan $96.25. Perhitungan yang sama untuk write 2x menghasilkan sekitar 53 persen untuk cache 1 hour. Jadi, rasio cache hit 50 persen masih memerlukan biaya $105.00, yang tetap lebih tinggi daripada biaya tanpa cache. Pada 90 persen, keduanya menghasilkan $21.50 dan $29.00. Pada 99 persen, cache dengan durasi lebih singkat mencapai $11.15, mendekati batas minimum sebesar sepersepuluh harga tanpa cache.

Rasio cache hit adalah metrik yang harus dipantau karena, setelah ukuran prefix ditetapkan, metrik ini merupakan satu-satunya input yang dapat Anda kendalikan.

Prefix yang layak dijadikan breakpoint

Sebuah request dapat membawa hingga empat cache breakpoint. Jadi, pertanyaannya adalah blok mana yang layak diberi breakpoint. Kandidatnya adalah blok yang identik byte demi byte pada setiap request dan cukup besar untuk memberikan dampak. Grafik di bawah ini menghitung biaya empat bentuk umum untuk 1,000 request dengan hit rate 90 persen pada cache 5 menit.

[
  {
    "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"
  }
]

System prompt tanpa tambahan apa pun, dengan 2,000 token, menghemat $7.85 per 1,000 request dibandingkan biaya tanpa cache sebesar $10.00. Pada volume tinggi, nilainya nyata, tetapi hal ini belum menunjukkan alasan caching menarik. Jika definisi tool ditambahkan, ukurannya menjadi 8,000 token dan penghematannya menjadi $31.40. Dokumen kebijakan 25,000 token yang menjadi dasar pertanyaan setiap request menghemat $98.12. Baris terakhir adalah yang mengubah arsitektur: konteks codebase atau transkrip sebesar 120,000 token berbiaya $600.00 tanpa cache dan $129.00 dengan cache, sehingga menghemat $471.00.

Penghematan meningkat seiring ukuran prefix dan hit rate, serta tidak dipengaruhi hal lain. Hal ini mengubah penilaian tentang apa yang layak dimasukkan ke prompt: biaya sebenarnya satu juta token Claude turun menjadi sepersepuluh dari harga tercantum untuk apa pun yang Anda kirim lebih dari sekali.

Tampilan pada tagihan bulanan

Bagan di bawah ini menggunakan prefix 8,000 token dari bagian sebelumnya, prompt sistem serta definisi alat, dengan tingkat cache hit 90 persen, lalu menskalakannya ke volume permintaan bulanan.

[
  {
    "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"
  }
]

Pada 10,000 permintaan per bulan, penghematannya adalah $314.00, yaitu selisih antara $400.00 dan $86.00. Pada 100,000 permintaan, penghematannya adalah $3,140.00. Pada satu juta permintaan, tagihan input tanpa cache adalah $40,000.00, dan caching menghapus $31,400.00 dari biaya tersebut. Angka ini hanya mencakup input token. Output dihargai secara terpisah, dan caching tidak memengaruhinya. Ingat hal ini sebelum menjanjikan pengurangan tagihan sebesar 90 persen kepada siapa pun. Caching melengkapi kebiasaan lain yang lebih luas dalam mengendalikan tagihan AI agent di VPS.

Cara membuktikan bahwa cache berfungsi

Jangan hanya mengandalkan desain. Baca blok usage pada respons. Setiap respons Messages API (application programming interface) melaporkan jumlah token yang ditulis ke cache, jumlah token yang dibaca dari cache, dan jumlah token baru yang harus diproses.

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)

Jalankan dua kali dengan dokumen yang sama dan pertanyaan yang berbeda. Panggilan pertama melaporkan cache_creation_input_tokens yang bukan nol dan cache_read_input_tokens yang nol. Panggilan kedua menunjukkan kebalikannya karena prefix ditemukan. input_tokens hanya menghitung token setelah breakpoint terakhir, sehingga pada panggilan kedua yang sehat nilainya kecil, biasanya hanya pesan pengguna yang baru. Kedua panggilan tetap dikenai biaya karena Claude API tidak memiliki free tier, meskipun untuk prefix 20,000 token, harga pasangan panggilan tersebut sekitar empat belas sen.

Pemeriksaan yang sama dari shell, menggunakan request body yang telah Anda simpan ke request.json:

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'

Panggilan kedua yang sehat akan mencetak keluaran seperti ini:

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

Satu baris menunjukkan kondisi sebenarnya. Jika cache_read_input_tokens tetap 0 pada setiap panggilan, Anda membayar biaya penulisan 1.25x setiap kali, tetapi tidak mendapatkan manfaat apa pun.

Untuk masa berlaku 1 jam, breakpoint menyertakan time to live (TTL):

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

Tersedia juga caching otomatis: satu field cache_control pada level teratas request, setelah itu API mengelola breakpoint seiring percakapan bertambah. Fitur ini menggunakan satu dari empat slot breakpoint Anda. Mulailah dari sini. Beralihlah ke breakpoint eksplisit jika Anda perlu menentukan lokasi batas secara tepat.

Aturan urutan yang menghancurkan hit rate

Cache mencocokkan awalan byte demi byte dari awal request. Request disusun dalam urutan tetap: tools, lalu system, kemudian messages. Perubahan pada tingkat mana pun akan membatalkan tingkat tersebut dan semua tingkat setelahnya. Jika Anda mengedit satu deskripsi tool, system prompt dan seluruh riwayat messages ikut dibatalkan, meskipun Anda tidak mengubahnya.

Hal ini menghasilkan satu aturan tanpa pengecualian. Apa pun yang berubah antarpanggilan harus ditempatkan setelah semua hal yang tidak berubah.

Penyebab yang paling umum adalah timestamp. Baris yang berisi Current time: 2026-08-03T14:07:11Z di bagian atas system prompt menjamin hit rate 0 persen, karena hash awalan berbeda pada setiap panggilan dan tidak ada entri sebelumnya yang dapat mencocokkannya. Pindahkan baris tersebut ke user message, di bagian akhir. Session identifier atau nonce per request menimbulkan masalah yang sama dan memiliki solusi yang sama. Dokumen yang diambil dan berbeda pada setiap request juga harus ditempatkan setelah blok yang di-cache. Jika tidak, setiap token yang stabil akan terdorong ke belakang boundary yang terus berubah.

Penyebab kedua adalah menempatkan breakpoint pada blok yang berubah. Penulisan cache terjadi pada breakpoint. Jadi, jika blok tersebut berbeda setiap kali, tidak ada konten stabil yang pernah disimpan, dan proses lookback hanya menemukan entri yang ditulis request sebelumnya pada breakpoint yang juga berubah-ubah. Tempatkan cache_control pada blok terakhir yang kontennya identik di seluruh request.

Penyebab ketiga adalah perubahan parameter yang tidak Anda anggap sebagai konten prompt. Model yang berbeda memiliki cache yang berbeda. Perubahan tool choice membatalkan cache mulai dari tingkat system dan seterusnya. Menambahkan atau menghapus tool membatalkan semuanya.

Prefiks minimum dan no-op diam-diam

Prefiks yang lebih pendek daripada minimum model tidak di-cache, dan tidak ada informasi yang memberi tahu Anda. Tidak ada error atau peringatan. Request berhasil, dan kedua penghitung menunjukkan 0. Per Agustus 2026, minimum yang dipublikasikan adalah:

• 512 token pada Claude Opus 5 dan Claude Fable 5
• 1,024 token pada Claude Sonnet 5 dan Claude Opus 4.8
• 4,096 token pada Claude Haiku 4.5

Jika kedua penghitung menunjukkan 0 pada request yang menurut Anda di-cache, periksa panjang prefiks terlebih dahulu. Ini juga menjadi alasan model termurah tidak otomatis menjadi yang termurah untuk workload caching. Claude Haiku 4.5 memerlukan prefiks yang delapan kali lebih panjang daripada Claude Opus 5 agar caching dapat berjalan, sehingga system prompt sepanjang 2,000 token akan di-cache pada satu model tetapi diabaikan secara diam-diam pada model lainnya.

Di mana Claude Code menyimpan cache untuk Anda dan di mana cache tidak dapat membantu

Claude Code menyimpan prefix-nya sendiri dalam cache. System prompt dan definisi tool berada di bagian awal setiap request dan tidak berubah, sehingga ditulis sekali lalu dibaca kembali selama sisa sesi. Karena itu, biaya per giliran dalam sesi panjang jauh lebih rendah daripada yang ditunjukkan oleh ukuran konteks. Hal ini terlihat pada penghitung yang dijelaskan dalam cara Claude Code melaporkan penggunaan token.

Cache tidak dapat membantu jika Anda mengedit bagian dekat awal konteks. Riwayat percakapan hanya dapat ditambahkan, sehingga giliran baru biasanya memperpanjang prefix yang sudah tersimpan dalam cache. Mengedit file yang dibaca di awal sesi akan mengubah isi di tengah prefix tersebut. Akibatnya, setiap token setelah perubahan harus ditulis ulang. Jeda tidak aktif yang panjang memiliki efek yang sama karena entri cache kedaluwarsa dan giliran berikutnya harus membayar penulisan penuh. Keduanya bukan bug. Keduanya merupakan penerapan aturan prefix sesuai fungsinya.

Jika Anda menulis client sendiri, terapkan layout tersebut sejak request pertama dan jangan menambahkannya belakangan. Susun pemanggilan seperti pada aplikasi Claude API pertama di VPS, dengan blok yang stabil di awal dan blok yang berubah-ubah di bagian akhir.

Mode kegagalan dan hal yang akan Anda lihat

Setiap panggilan adalah operasi tulis. cache_creation_input_tokens bernilai non-zero pada setiap request, sedangkan cache_read_input_tokens tetap 0. Ada sesuatu pada atau sebelum breakpoint yang berubah di antara panggilan. Cetak 200 karakter pertama dari prefix yang Anda susun pada dua request berturut-turut, lalu bandingkan secara visual.

Kedua counter bernilai 0. Prefix lebih pendek daripada minimum model, atau field cache_control tidak pernah sampai ke API. Hitung token prefix terlebih dahulu, lalu catat request body yang benar-benar Anda kirim.

Pembacaan berhasil, lalu berhenti. Terjadi serangkaian hit, kemudian operasi tulis, lalu hit lagi. Jeda antar-request lebih lama daripada lifetime. Terima operasi tulis tersebut, atau gunakan TTL 1 hour setelah memastikan hit rate Anda melewati 53 percent.

Hit rate turun setelah deploy. Deskripsi tool diedit atau model diubah. Keduanya membatalkan seluruh prefix. Setiap deploy yang mengubah prompt akan menyebabkan satu putaran operasi tulis yang mahal.

Tagihan naik setelah caching diaktifkan. Hit rate Anda berada di bawah titik impas. Pada cache 5 minute, jika nilainya di bawah sekitar 22 percent, mengirim prefix tanpa caching lebih murah. Hal yang sama berlaku pada cache 1 hour jika nilainya di bawah sekitar 53 percent.

FAQ

Berapa kali prompt harus digunakan ulang sebelum caching menjadi sepadan?

Satu kali, pada cache 5 menit. Biaya penulisan adalah 1.25x input dasar, sedangkan biaya pembacaan adalah 0.1x. Jadi, N permintaan tanpa cache berbiaya N, sementara N permintaan dengan cache berbiaya 1.25 ditambah 0.1 dikali N dikurangi 1. Keduanya berpotongan pada N = 1.28, sehingga permintaan kedua sudah lebih hemat. Cache 1 jam memiliki biaya penulisan 2x dan berpotongan pada N = 2.11, sehingga memerlukan dua pembacaan.

Mengapa cache_read_input_tokens selalu bernilai nol?

Periksa panjang prefix terlebih dahulu: jika lebih pendek dari minimum model, yaitu 512 token pada Claude Opus 5 dan 4,096 pada Claude Haiku 4.5 per August 2026, caching dilewati secara diam-diam dan kedua penghitung bernilai 0. Jika prefix cukup panjang, cari konten yang berubah di antara pemanggilan dan berada pada atau sebelum breakpoint, seperti timestamp atau pengenal sesi dalam system prompt. Jika penghitung sebelumnya berfungsi lalu berhenti, jeda antara permintaan lebih panjang daripada masa berlaku cache.

Apakah prompt caching mengubah jawaban Claude?

Tidak. Cache menyimpan bentuk token yang telah diproses dan sebelumnya Anda kirimkan. Model menerima prompt yang sama pada kedua kondisi. Ini adalah fitur penagihan dan latensi, bukan perubahan perilaku. Artinya, Anda dapat mengaktifkannya pada prompt yang sudah berfungsi tanpa menjalankan ulang evaluasi.

Apakah saya perlu membayar cache 1 jam?

Hanya jika trafik Anda memiliki jeda lebih dari 5 menit dan hit rate Anda tetap sekitar 53 persen atau lebih. Biaya penulisan 2x memiliki dampak negatif dua kali lipat dibandingkan biaya penulisan 1.25x ketika cache tidak terkena hit. Entri cache 5 menit diperbarui setiap kali terkena hit, sehingga trafik yang stabil membuatnya tetap aktif dengan biaya pembacaan tanpa perlu membayar masa berlaku yang lebih panjang.