Claude Prompt Caching: Hitung Titik Impas

Biaya caching prompt sebelum menghasilkan penghematan

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

Pertukarannya adalah biaya tambahan sekarang untuk mendapatkan potongan harga kemudian. Anda membayar lebih sekali untuk menyimpan sebuah prefix. Setiap permintaan berikutnya yang dimulai dengan byte yang sama persis hanya membayar sepersepuluh dari harga input normal untuk bagian tersebut. Jika sebuah prefix tidak pernah digunakan kembali selama masa berlakunya, Anda membayar biaya tambahan 25 persen tanpa memperoleh manfaat.

Titik impas, dalam satu baris aljabar

Misalkan B adalah biaya input dasar prefix jika Anda mengirimkannya tanpa cache. Tanpa caching, N request memerlukan biaya sebesar N kali B. Dengan cache 5 menit, request pertama menulis prefix dengan biaya 1.25B, sedangkan N dikurangi 1 request lainnya membacanya dengan biaya 0.1B. Samakan kedua biaya tersebut 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 berdurasi panjang memerlukan dua pembacaan sebelum mencapai titik impas. Karena itu, cache ini bukan pilihan default.

Grafik di bawah menghitung biaya ini untuk prefix 20,000 token pada Claude Opus 5, dengan tarif input dasar $5 per juta token per August 2026. Kalikan setiap angka dengan 0.6 untuk model dengan tarif $3 per juta. 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. Jadi, caching pada prompt yang hanya digunakan sekali merupakan kerugian murni. Pada request kedua, cache 5 menit berbiaya $0.135, dibandingkan $0.20 tanpa cache. Cache 1 jam masih lebih mahal pada titik tersebut, yaitu $0.21 dibandingkan $0.20 yang sama, dan baru lebih murah daripada biaya tanpa cache pada request ketiga: $0.22 dibandingkan $0.30. Pada 20 request, selisihnya adalah $2.00 dibandingkan $0.315.

Cache hit juga memperbarui masa aktif entri. Karena itu, tabel harga yang dipublikasikan menyebut kolom tersebut sebagai cache hits and refreshes. Dengan demikian, endpoint yang sibuk dapat mempertahankan entri 5 menit tanpa batas waktu dengan tarif pembacaan, sedangkan masa berlaku 1 jam hanya membuat penulisan 2x sepadan jika trafik Anda memiliki jeda yang nyata.

Biaya tingkat cache hit yang rendah

Trafik nyata mengalami cache miss. Request yang mengalami cache miss tetapi tetap membawa breakpoint akan dikenai biaya sebagai write. Karena itu, cara yang tepat untuk memodelkannya adalah menghitung biaya sebagai fungsi dari tingkat cache hit. Grafik berikut menunjukkan perhitungannya untuk 1,000 request, yang masing-masing membawa prefix 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 tingkat cache hit 0 persen, biaya yang Anda bayarkan 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 tingkat cache hit sekitar 22 persen. Karena itu, tingkat 25 persen sudah menunjukkan $96.25. Perhitungan yang sama untuk write 2x menghasilkan sekitar 53 persen untuk cache 1 hour. Jadi, tingkat cache hit 50 persen masih dikenai biaya $105.00, yang berada di atas garis tanpa cache. Pada tingkat 90 persen, keduanya mencapai $21.50 dan $29.00. Pada tingkat 99 persen, cache berdurasi pendek mencapai $11.15, mendekati batas minimum sebesar sepersepuluh harga tanpa cache.

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

Awalan mana yang layak diberi breakpoint

Sebuah request dapat membawa hingga empat cache breakpoint. Karena itu, pertanyaannya adalah blok mana yang layak diberi breakpoint. Kandidatnya adalah blok yang byte-nya identik pada setiap call dan cukup besar untuk memberikan dampak. Grafik di bawah 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 dasar dengan token 2,000 menghemat $7.85 per 1,000 request dibandingkan biaya tanpa cache sebesar $10.00. Pada volume tinggi, jumlah ini nyata, tetapi bukan alasan utama caching menarik. Jika definisi tool ditambahkan, ukurannya menjadi 8,000 token dan penghematannya $31.40. Dokumen kebijakan sepanjang 25,000 token yang menjadi dasar pertanyaan pada setiap request menghemat $98.12. Baris terakhir adalah bagian yang mengubah arsitektur: konteks codebase atau transkrip sepanjang 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 hal yang layak dimasukkan ke prompt: biaya sebenarnya dari satu juta token Claude turun menjadi sepersepuluh dari harga yang tercantum untuk apa pun yang dikirim lebih dari sekali.

Gambaran pada tagihan bulanan

Grafik di bawah menggunakan prefiks token 8,000 dari bagian sebelumnya, prompt sistem dan definisi alat, dengan tingkat hit 90 persen, lalu memproyeksikannya 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 token input. Output dihargai secara terpisah, dan caching tidak berpengaruh terhadapnya. Hal ini perlu diingat sebelum Anda menjanjikan pengurangan tagihan sebesar 90 persen. Caching melengkapi kebiasaan lain untuk mengendalikan tagihan AI agent pada VPS.

Cara membuktikan bahwa cache berfungsi

Jangan mengandalkan desainnya. Baca blok penggunaan pada respons. Setiap respons Messages API (application programming interface) melaporkan token yang ditulis ke cache, token yang dibaca dari cache, dan 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 bernilai nol. Panggilan kedua membalik hasil tersebut karena prefix ditemukan. input_tokens hanya menghitung token setelah breakpoint terakhir. Jadi, pada panggilan kedua yang berhasil, nilainya kecil, biasanya hanya pesan pengguna yang baru.

Pemeriksaan yang sama dari shell, menggunakan request body yang telah disimpan 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 berhasil mencetak sesuatu seperti berikut:

{
  "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 tanpa memperoleh manfaat apa pun.

Untuk lifetime 1 hour, breakpoint memiliki time to live (TTL):

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

Caching otomatis juga tersedia: satu field cache_control pada tingkat teratas request. Setelah itu, API mengelola breakpoint seiring bertambahnya percakapan. Fitur ini menggunakan satu dari empat slot breakpoint Anda. Mulailah dengan opsi ini. Gunakan breakpoint eksplisit ketika Anda perlu menentukan lokasi batas secara tepat.

Aturan pengurutan yang menghancurkan tingkat cache hit

Cache mencocokkan awalan byte demi byte sejak 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 serta system prompt, seluruh riwayat messages ikut dibatalkan, meskipun Anda tidak mengubahnya.

Hal ini menghasilkan satu aturan tanpa pengecualian. Apa pun yang berubah di antara pemanggilan 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 tingkat cache hit 0 persen, karena hash awalan berbeda pada setiap pemanggilan 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 harus ditangani dengan cara yang sama. Dokumen hasil retrieval yang berbeda pada setiap request juga harus ditempatkan setelah blok yang di-cache. Jika tidak, dokumen tersebut mendorong semua token yang stabil ke belakang boundary yang 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. Proses lookback hanya menemukan entri yang ditulis request sebelumnya pada breakpoint yang juga berubah-ubah. Tempatkan cache_control pada blok terakhir yang isinya identik di antara 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. Penambahan atau penghapusan tool membatalkan semuanya.

Prefiks minimum dan no-op senyap

Prefiks yang lebih pendek daripada minimum model tidak akan disimpan dalam cache, dan tidak ada informasi yang memberi tahu Anda tentang hal itu. Tidak ada error atau peringatan. Request berhasil dan kedua penghitung menunjukkan 0. Per Agustus 2026, batas 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 menggunakan cache, periksa panjang prefiks terlebih dahulu. Ini juga menjelaskan mengapa model termurah tidak otomatis menjadi model termurah untuk beban kerja caching. Claude Haiku 4.5 memerlukan prefiks delapan kali lebih panjang daripada Claude Opus 5 agar caching dapat digunakan, sehingga system prompt sepanjang 2,000 token disimpan dalam cache pada satu model, tetapi diabaikan secara diam-diam pada model lainnya.

Lokasi Claude Code menyimpan cache untuk Anda, dan hal yang tidak dapat dilakukannya

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

Cache tidak dapat membantu jika Anda mengedit bagian dekat awal context. Riwayat percakapan hanya dapat ditambahkan, sehingga giliran baru biasanya memperpanjang prefix yang sudah tersimpan dalam cache. Jika Anda mengedit file yang dibaca pada awal sesi, isinya berubah di tengah prefix tersebut. Semua token setelah perubahan harus ditulis ulang. Jeda idle yang panjang menimbulkan efek yang sama karena entri cache kedaluwarsa dan giliran berikutnya harus melakukan penulisan penuh. Keduanya bukan bug. Keduanya merupakan penerapan aturan prefix sesuai fungsinya.

Jika Anda menulis client sendiri, terapkan layout ini sejak request pertama, bukan dengan menyesuaikannya kemudian. Bangun pemanggilan seperti yang dilakukan dalam aplikasi Claude API pertama pada VPS, dengan blok yang stabil di bagian 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. Sesuatu pada atau sebelum breakpoint berubah di antara panggilan. Cetak 200 karakter pertama dari prefix yang telah dirakit pada dua request berturut-turut, lalu bandingkan secara visual.

Kedua counter bernilai 0. Prefix berada di bawah 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. Serangkaian hit terjadi, kemudian satu operasi tulis, lalu hit terjadi lagi. Jeda antar-request lebih lama daripada masa berlaku cache. Terima operasi tulis tersebut, atau pindah ke TTL 1 hour setelah memastikan bahwa hit rate Anda melebihi 53 persen.

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

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

FAQ

Berapa kali prompt harus digunakan ulang sebelum caching mulai menguntungkan?

Satu kali, pada cache 5 menit. Penulisan memerlukan biaya 1.25x input dasar, sedangkan pembacaan memerlukan biaya 0.1x. Dengan demikian, N permintaan tanpa cache memerlukan biaya N, sedangkan N permintaan dengan cache memerlukan biaya 1.25 ditambah 0.1 dikali N dikurangi 1. Keduanya berpotongan pada N = 1.28, sehingga permintaan kedua sudah lebih menguntungkan. Cache 1 jam melakukan penulisan dengan biaya 2x dan berpotongan pada N = 2.11, sehingga memerlukan dua pembacaan.

Mengapa cache_read_input_tokens selalu bernilai 0?

Periksa panjang prefix terlebih dahulu. Jika panjangnya di bawah 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 session identifier dalam system prompt. Jika penghitung sebelumnya berfungsi lalu berhenti, jeda antarpermintaan lebih lama daripada masa berlaku cache.

Apakah prompt caching mengubah jawaban Claude?

Tidak. Cache menyimpan bentuk token yang sudah diproses dan telah Anda kirim, sedangkan 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 mencapai kira-kira 53 persen. Biaya penulisan 2x memiliki kerugian dua kali lipat dibandingkan biaya penulisan 1.25x saat cache miss. Entri cache 5 menit diperbarui setiap kali terjadi cache hit, sehingga trafik yang stabil membuatnya tetap aktif dengan biaya pembacaan tanpa perlu membayar masa berlaku yang lebih panjang.