Claude Platform Docs
PesanManajemen konteks

Caching prompt

Cache prefiks prompt dengan cache_control untuk memangkas biaya dan latensi, menggunakan caching otomatis atau breakpoint eksplisit dengan TTL 5 menit atau 1 jam.

Penggunaan berbeda menurut produk

Messages API
Aktifkan dengan cache_control, di level teratas atau pada blok.
Managed Agents
Selalu aktifEntri cache menggunakan masa berlaku 5 menit secara default, dan pembacaan serta penulisan cache muncul dalam penggunaan sesi.

“Prompt caching” (caching prompt) mengoptimalkan penggunaan API Anda dengan memungkinkan API melanjutkan dari prefiks tertentu dalam prompt Anda. Ini secara signifikan mengurangi waktu pemrosesan dan biaya untuk tugas berulang atau prompt dengan elemen yang konsisten.

Ada dua cara untuk mengaktifkan caching prompt:

  • Caching otomatis: Tambahkan satu field cache_control di tingkat teratas permintaan Anda. Sistem secara otomatis menerapkan “cache breakpoint” (titik henti cache) ke blok terakhir yang dapat di-cache dan memindahkannya maju seiring percakapan bertambah. Paling cocok untuk percakapan multi-giliran di mana riwayat pesan yang terus bertambah harus di-cache secara otomatis.
  • Cache breakpoint eksplisit: Tempatkan cache_control langsung pada blok konten individual untuk kontrol yang lebih rinci atas apa saja yang di-cache.

Salah satu cara untuk memulai adalah dengan caching otomatis:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system="You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",
    messages=[
        {
            "role": "user",
            "content": "Analyze the major themes in 'Pride and Prejudice'.",
        }
    ],
)
print(response.usage.model_dump_json())

Dengan caching otomatis, sistem meng-cache semua konten hingga dan termasuk blok terakhir yang dapat di-cache. Pada permintaan berikutnya dengan prefiks yang sama, konten yang di-cache digunakan kembali secara otomatis.


Cara kerja caching prompt

Saat Anda mengirim permintaan dengan caching prompt diaktifkan:

  1. Sistem memeriksa apakah prefiks prompt, hingga breakpoint cache yang ditentukan, sudah di-cache dari kueri terbaru.
  2. Jika ditemukan, sistem menggunakan versi yang di-cache, sehingga mengurangi waktu pemrosesan dan biaya.
  3. Jika tidak, sistem memproses prompt lengkap dan meng-cache prefiks setelah respons dimulai.

Ini sangat berguna untuk:

  • Prompt dengan banyak contoh
  • Konteks atau informasi latar belakang dalam jumlah besar
  • Tugas berulang dengan instruksi yang konsisten
  • Percakapan multi-giliran yang panjang

Secara default, cache memiliki masa hidup 5 menit. Cache diperbarui tanpa biaya tambahan setiap kali konten yang di-cache digunakan.

Masa hidup diukur sejak awal permintaan yang menulis atau membaca entri cache, bukan sejak akhir responsnya. Waktu yang dihabiskan untuk menghasilkan respons dihitung terhadap masa hidup: jika respons membutuhkan 4 menit untuk di-stream, permintaan lanjutan yang menggunakan kembali prefiks yang di-cache yang sama harus dimulai dalam waktu sekitar 1 menit setelah respons tersebut selesai.

Jika 5 menit terlalu singkat, Anda dapat menggunakan durasi cache 1 jam dengan biaya tambahan (lihat Harga).

Caching prompt mencakup seluruh prefiks: tools, system, dan messages (dalam urutan tersebut), hingga dan termasuk blok yang ditandai dengan cache_control.


Harga

Caching prompt memiliki harganya sendiri. Tabel berikut menunjukkan harga per juta token untuk setiap model yang didukung:

ModelToken dasarCaching prompt
NamaInputOutputPenulisan 5 mntPenulisan 1 jamHit dan penyegaran
Claude Fable 5.2For demanding reasoning and long-horizon agentic work
US$8 / MTok
US$40 / MTok
US$10 / MTok
US$16 / MTok
US$0,20 / MTok1
Claude Opus 5.5For long-running agentic coding and knowledge work
US$4 / MTok
US$20 / MTok
US$5 / MTok
US$8 / MTok
US$0,20 / MTok2
Claude Sonnet 5.5The best combination of speed and intelligence
US$2 / MTok
US$10 / MTok
US$2,50 / MTok
US$4 / MTok
US$0,10 / MTok2
Claude Haiku 5.5For high-volume, latency-sensitive tasks such as classification, extraction, and routing
US$0,10 / MTokuntuk prompt hingga 100.000 token
US$0,50 / MTok
US$0,125 / MTok
US$0,20 / MTok
US$0,01 / MTok
US$0,50 / MTokuntuk prompt di atas 100.000 token
US$2,50 / MTok
US$0,625 / MTok
US$1 / MTok
US$0,05 / MTok
US$8 / MTok
US$40 / MTok
US$10 / MTok
US$16 / MTok
US$0,20 / MTok1
US$10 / MTok
US$50 / MTok
US$12,50 / MTok
US$20 / MTok
US$0,25 / MTok1
US$10 / MTok
US$50 / MTok
US$12,50 / MTok
US$20 / MTok
US$0,25 / MTok1
US$10 / MTok
US$50 / MTok
US$12,50 / MTok
US$20 / MTok
US$1 / MTok
US$10 / MTok
US$50 / MTok
US$12,50 / MTok
US$20 / MTok
US$1 / MTok
US$5 / MTok
US$25 / MTok
US$6,25 / MTok
US$10 / MTok
US$0,50 / MTok
US$5 / MTok
US$25 / MTok
US$6,25 / MTok
US$10 / MTok
US$0,50 / MTok
US$5 / MTok
US$25 / MTok
US$6,25 / MTok
US$10 / MTok
US$0,50 / MTok
US$5 / MTok
US$25 / MTok
US$6,25 / MTok
US$10 / MTok
US$0,50 / MTok
US$5 / MTok
US$25 / MTok
US$6,25 / MTok
US$10 / MTok
US$0,50 / MTok
Claude Opus 4.1
US$15 / MTok
US$75 / MTok
US$18,75 / MTok
US$30 / MTok
US$1,50 / MTok
Claude Opus 4
US$15 / MTok
US$75 / MTok
US$18,75 / MTok
US$30 / MTok
US$1,50 / MTok
US$2 / MTok
US$10 / MTok
US$2,50 / MTok
US$4 / MTok
US$0,20 / MTok
US$3 / MTok
US$15 / MTok
US$3,75 / MTok
US$6 / MTok
US$0,30 / MTok
US$3 / MTok
US$15 / MTok
US$3,75 / MTok
US$6 / MTok
US$0,30 / MTok
Claude Sonnet 4
US$3 / MTok
US$15 / MTok
US$3,75 / MTok
US$6 / MTok
US$0,30 / MTok
US$1 / MTok
US$5 / MTok
US$1,25 / MTok
US$2 / MTok
US$0,10 / MTok

1 Cache hit dan penyegaran cache pada Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, dan Claude Mythos 5.1 dikenakan harga 0,025x harga input dasar.

2 Cache hit dan penyegaran cache pada Claude Opus 5.5 dan Claude Sonnet 5.5 dikenakan harga 0,05x harga input dasar.

Semua model lainnya menggunakan pengali standar 0,1x.


Model yang didukung

Caching prompt (baik otomatis maupun eksplisit) didukung pada semua model Claude yang aktif.


Caching otomatis

Caching otomatis mengaktifkan caching prompt dengan satu field. Alih-alih menempatkan cache_control pada blok konten individual, tambahkan satu field cache_control di tingkat teratas body permintaan Anda. Sistem secara otomatis menerapkan breakpoint cache ke blok terakhir yang dapat di-cache.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system="You are a helpful assistant that remembers our conversation.",
    messages=[
        {"role": "user", "content": "My name is Alex. I work on machine learning."},
        {
            "role": "assistant",
            "content": "Nice to meet you, Alex! How can I help with your ML work today?",
        },
        {"role": "user", "content": "What did I say I work on?"},
    ],
)
print(response.usage.model_dump_json())

Cara kerja caching otomatis dalam percakapan multi-giliran

Dengan caching otomatis, titik cache bergerak maju secara otomatis seiring percakapan bertambah. Setiap permintaan baru meng-cache semuanya hingga blok terakhir yang dapat di-cache, dan konten sebelumnya dibaca dari cache.

PermintaanKontenPerilaku cache
Permintaan 1System
+ User(1) + Asst(1)
+ User(2) ◀ cache
Semuanya ditulis ke cache
Permintaan 2System
+ User(1) + Asst(1)
+ User(2) + Asst(2)
+ User(3) ◀ cache
System hingga User(2) dibaca dari cache;
Asst(2) + User(3) ditulis ke cache
Permintaan 3System
+ User(1) + Asst(1)
+ User(2) + Asst(2)
+ User(3) + Asst(3)
+ User(4) ◀ cache
System hingga User(3) dibaca dari cache;
Asst(3) + User(4) ditulis ke cache

Breakpoint cache secara otomatis berpindah ke blok terakhir yang dapat di-cache dalam setiap permintaan, sehingga Anda tidak perlu memperbarui penanda cache_control apa pun seiring percakapan bertambah.

Dukungan TTL

Secara default, caching otomatis menggunakan TTL 5 menit. Anda dapat menentukan TTL 1 jam dengan harga 2x harga token input dasar:

{ "cache_control": { "type": "ephemeral", "ttl": "1h" } }

Menggabungkan dengan caching tingkat blok

Caching otomatis kompatibel dengan breakpoint cache eksplisit. Saat digunakan bersama, breakpoint cache otomatis menggunakan salah satu dari 4 slot breakpoint yang tersedia.

Ini memungkinkan Anda menggabungkan kedua pendekatan. Misalnya, gunakan breakpoint eksplisit untuk meng-cache prompt sistem Anda, sementara caching otomatis menangani percakapan:

{
  "model": "claude-opus-5-5",
  "max_tokens": 1024,
  "cache_control": { "type": "ephemeral" },
  "system": [
    {
      "type": "text",
      "text": "You are a helpful assistant.",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [{ "role": "user", "content": "What are the key terms?" }]
}

Apa yang tetap sama

Caching otomatis menggunakan infrastruktur caching dasar yang sama. Harga, ambang batas token minimum, persyaratan urutan konteks, dan jendela lookback 20 blok semuanya berlaku sama seperti pada breakpoint eksplisit.

Kasus tepi

  • Jika blok terakhir sudah memiliki cache_control eksplisit dengan TTL yang sama, caching otomatis tidak melakukan apa-apa.
  • Jika blok terakhir memiliki cache_control eksplisit dengan TTL yang berbeda, API mengembalikan error 400.
  • Jika sudah ada 4 breakpoint tingkat blok eksplisit, API mengembalikan error 400 (tidak ada slot tersisa untuk caching otomatis).
  • Jika blok terakhir tidak memenuhi syarat sebagai target breakpoint cache otomatis, sistem secara diam-diam berjalan mundur untuk menemukan blok terdekat yang memenuhi syarat. Jika tidak ada yang ditemukan, caching dilewati.

Cache breakpoint eksplisit

Untuk kontrol lebih atas caching, Anda dapat menempatkan cache_control langsung pada blok konten individual. Ini berguna saat Anda perlu meng-cache bagian berbeda yang berubah dengan frekuensi berbeda, atau memerlukan kontrol rinci atas apa saja yang di-cache.

Menyusun prompt Anda

Tempatkan konten statis (definisi alat, instruksi sistem, konteks, contoh) di awal prompt Anda. Tandai akhir konten yang dapat digunakan kembali untuk caching menggunakan parameter cache_control.

Prefiks cache dibuat dalam urutan berikut: tools, system, lalu messages. Urutan ini membentuk hierarki di mana setiap tingkat dibangun di atas tingkat sebelumnya.

Cara kerja pemeriksaan prefiks otomatis

Anda dapat menggunakan hanya satu breakpoint cache di akhir konten statis Anda, dan sistem secara otomatis menemukan prefiks terpanjang yang sudah ditulis ke cache oleh permintaan sebelumnya. Memahami cara kerjanya membantu Anda mengoptimalkan strategi caching Anda.

Tiga prinsip inti:

  1. Penulisan cache hanya terjadi di breakpoint Anda. Menandai blok dengan cache_control menulis tepat satu entri cache: hash dari prefiks yang berakhir di blok tersebut. Sistem tidak menulis entri untuk posisi yang lebih awal. Karena hash bersifat kumulatif, mencakup semuanya hingga dan termasuk breakpoint, mengubah blok apa pun di atau sebelum breakpoint menghasilkan hash yang berbeda pada permintaan berikutnya.

  2. Pembacaan cache melihat ke belakang untuk entri yang ditulis oleh permintaan sebelumnya. Pada setiap permintaan, sistem menghitung hash prefiks di breakpoint Anda dan memeriksa entri cache yang cocok. Jika tidak ada, sistem berjalan mundur satu blok pada satu waktu, memeriksa apakah hash prefiks di setiap posisi sebelumnya cocok dengan sesuatu yang sudah ada di cache. Sistem mencari penulisan sebelumnya, bukan konten yang stabil.

  3. Jendela lookback adalah 20 blok. Sistem memeriksa paling banyak 20 posisi untuk setiap breakpoint, dengan menghitung breakpoint itu sendiri sebagai yang pertama. Jika sistem tidak menemukan entri yang cocok dalam jendela tersebut, pemeriksaan berhenti (atau dilanjutkan dari breakpoint eksplisit berikutnya, jika ada). Pada Claude API, rangkaian blok tool_use berturut-turut dihitung sebagai satu posisi, begitu juga rangkaian blok tool_result berturut-turut, sehingga giliran dengan banyak panggilan alat paralel tidak dengan sendirinya mendorong entri permintaan sebelumnya keluar dari jendela.

Contoh: Lookback dalam percakapan yang terus bertambah

Anda menambahkan blok baru setiap giliran dan mengatur cache_control pada blok terakhir setiap permintaan:

  • Giliran 1: 10 blok, breakpoint pada blok 10. Belum ada entri cache sebelumnya. Sistem menulis entri di blok 10.
  • Giliran 2: 15 blok, breakpoint pada blok 15. Blok 15 tidak memiliki entri, sehingga sistem berjalan mundur ke blok 10 dan menemukan entri giliran 1. Cache hit di blok 10. Sistem hanya memproses blok 11 hingga 15 dari awal dan menulis entri baru di blok 15.
  • Giliran 3: 35 blok, breakpoint pada blok 35. Sistem memeriksa 20 posisi (blok 35 hingga 16) dan tidak menemukan apa pun. Entri giliran 2 di blok 15 berada satu posisi di luar jendela, sehingga tidak ada cache hit. Menambahkan breakpoint kedua di blok 15 memulai jendela lookback kedua di sana, yang menemukan entri giliran 2.

Kesalahan umum: Breakpoint pada konten yang berubah setiap permintaan

Prompt Anda memiliki konteks sistem statis yang besar (blok 1 hingga 5) diikuti oleh blok per permintaan yang berisi timestamp dan pesan pengguna (blok 6). Anda mengatur cache_control pada blok 6:

  • Permintaan 1: Penulisan cache di blok 6. Hash mencakup timestamp.
  • Permintaan 2: Timestamp berbeda, sehingga hash prefiks di blok 6 berbeda. Lookback berjalan melalui blok 5, 4, 3, 2, dan 1, tetapi sistem tidak pernah menulis entri di posisi mana pun tersebut. Tidak ada cache hit. Anda membayar penulisan cache baru pada setiap permintaan dan tidak pernah mendapatkan pembacaan.

Lookback tidak menemukan konten stabil di belakang breakpoint Anda lalu meng-cache-nya. Lookback menemukan entri yang sudah ditulis oleh permintaan sebelumnya, dan penulisan hanya terjadi di breakpoint. Pindahkan cache_control ke blok 5, blok terakhir yang tetap sama di seluruh permintaan, dan setiap permintaan berikutnya membaca prefiks yang di-cache. Caching otomatis memiliki masalah yang sama: caching otomatis menempatkan breakpoint pada blok terakhir yang dapat di-cache, yang dalam struktur ini adalah blok yang berubah setiap permintaan, jadi gunakan breakpoint eksplisit pada blok 5 sebagai gantinya.

Poin penting: Tempatkan cache_control pada blok terakhir yang prefiksnya identik di seluruh permintaan yang ingin Anda bagikan cache-nya. Dalam percakapan yang terus bertambah, blok terakhir berfungsi selama setiap giliran menambahkan kurang dari 20 blok: konten sebelumnya tidak pernah berubah, sehingga lookback permintaan berikutnya menemukan penulisan sebelumnya. Untuk prompt dengan sufiks yang bervariasi (timestamp, konteks per permintaan, pesan yang masuk), tempatkan breakpoint di akhir prefiks statis, bukan pada blok yang bervariasi.

Kapan menggunakan beberapa breakpoint

Anda dapat menentukan hingga 4 cache breakpoint jika Anda ingin:

  • Meng-cache bagian berbeda yang berubah dengan frekuensi berbeda (misalnya, alat jarang berubah, tetapi konteks diperbarui setiap hari)
  • Memiliki kontrol lebih atas apa saja yang di-cache
  • Memastikan cache hit ketika percakapan yang terus bertambah mendorong breakpoint Anda 20 blok atau lebih melewati penulisan cache terakhir

Memahami biaya breakpoint cache

Cache breakpoint itu sendiri tidak menambah biaya apa pun. Anda hanya dikenakan biaya untuk:

  • Penulisan cache: Saat konten baru ditulis ke cache (25 persen lebih mahal dari token input dasar untuk TTL 5 menit)
  • Pembacaan cache: Saat konten yang di-cache digunakan (10 persen dari harga token input dasar, dengan pengecualian per model)
  • Token input reguler: Untuk konten apa pun yang tidak di-cache

Menambahkan lebih banyak breakpoint cache_control tidak meningkatkan biaya Anda; Anda tetap membayar jumlah yang sama berdasarkan konten apa yang benar-benar di-cache dan dibaca. Breakpoint memberi Anda kontrol atas bagian mana yang dapat di-cache secara independen.


Strategi dan pertimbangan caching

Batasan cache

Pada Claude API, Claude Platform on AWS, Claude Models on Google Cloud (Google managed), dan Microsoft Foundry, panjang prompt minimum yang dapat di-cache adalah:

Batas minimum ini berlaku di masing-masing platform tersebut tempat model tersedia.

Prompt yang lebih pendek tidak dapat di-cache, bahkan jika ditandai dengan cache_control. Setiap permintaan untuk meng-cache kurang dari jumlah token ini diproses tanpa caching, dan tidak ada error yang dikembalikan. Untuk memeriksa apakah prompt di-cache, lihat field usage respons: jika cache_creation_input_tokens dan cache_read_input_tokens keduanya 0, prompt tidak di-cache (kemungkinan karena tidak memenuhi persyaratan panjang minimum).

Jika prompt Anda sedikit kurang dari batas minimum untuk model dan platform Anda, memperluas konten yang di-cache untuk mencapai ambang batas sering kali sepadan. Pembacaan cache jauh lebih murah daripada token input yang tidak di-cache, sehingga mencapai batas minimum dapat mengurangi biaya untuk prompt yang sering digunakan kembali.

Untuk permintaan bersamaan, perhatikan bahwa entri cache baru tersedia setelah respons pertama dimulai. Jika Anda memerlukan cache hit untuk permintaan paralel, tunggu respons pertama sebelum mengirim permintaan berikutnya.

ephemeral adalah satu-satunya jenis cache yang didukung, yang secara default memiliki masa hidup 5 menit.

Apa yang dapat di-cache

Sebagian besar blok dalam permintaan dapat di-cache. Ini termasuk:

  • Alat: Definisi alat dalam array tools
  • Pesan sistem: Blok konten dalam array system
  • Pesan teks: Blok konten dalam array messages.content, untuk giliran pengguna maupun asisten
  • Gambar dan dokumen: Blok konten dalam array messages.content, pada giliran pengguna
  • Penggunaan alat dan hasil alat: Blok konten dalam array messages.content, pada giliran pengguna maupun asisten

Setiap elemen ini dapat di-cache, baik secara otomatis atau dengan menandainya menggunakan cache_control.

Apa yang tidak dapat di-cache

Meskipun sebagian besar blok permintaan dapat di-cache, ada beberapa pengecualian:

  • Blok pemikiran tidak dapat di-cache secara langsung dengan cache_control. Namun, blok pemikiran DAPAT di-cache bersama konten lain ketika muncul di giliran asisten sebelumnya. Saat di-cache dengan cara ini, blok tersebut DIHITUNG sebagai token input saat dibaca dari cache.

  • Blok sub-konten (seperti kutipan) itu sendiri tidak dapat di-cache secara langsung. Sebagai gantinya, cache blok tingkat teratas.

    Dalam kasus kutipan, blok konten dokumen tingkat teratas yang berfungsi sebagai bahan sumber untuk kutipan dapat di-cache. Ini memungkinkan Anda menggunakan caching prompt dengan kutipan secara efektif dengan meng-cache dokumen yang dirujuk oleh kutipan.

  • Blok teks kosong tidak dapat di-cache.

Apa yang membatalkan cache

Modifikasi pada konten yang di-cache dapat membatalkan sebagian atau seluruh cache.

Seperti dijelaskan dalam Menyusun prompt Anda, cache mengikuti hierarki: tools → system → messages. Perubahan di setiap tingkat membatalkan tingkat tersebut dan semua tingkat berikutnya.

Tabel berikut menunjukkan bagian cache mana yang dibatalkan oleh berbagai jenis perubahan. ✘ menunjukkan bahwa cache dibatalkan, sedangkan ✓ menunjukkan bahwa cache tetap valid.

Apa yang berubahCache alatCache sistemCache pesanDampak
Definisi alat✘✘✘Memodifikasi definisi alat (nama, deskripsi, parameter) membatalkan seluruh cache
Toggle pencarian web✓✘✘Mengaktifkan/menonaktifkan pencarian web memodifikasi prompt sistem
Toggle kutipan✓✘✘Mengaktifkan/menonaktifkan kutipan memodifikasi prompt sistem
Pengaturan kecepatan✓✘✘Beralih antara speed: "fast" dan kecepatan standar membatalkan cache sistem dan pesan
Pilihan alat✓✓✘Perubahan pada parameter tool_choice hanya memengaruhi blok pesan
Gambar✓✓✘Menambahkan/menghapus gambar di mana pun dalam prompt memengaruhi blok pesan
Parameter pemikiranSpesifik modelSpesifik model✘Konfigurasi pemikiran (mode, dan budget_tokens dalam mode diperpanjang) dirender ke dalam prompt, sehingga mengubahnya selalu membatalkan blok pesan; cache alat dan sistem juga dibatalkan pada model yang merender konfigurasi sebelum keduanya. Lihat Pemikiran dan caching prompt.
Pengaturan effortSpesifik modelSpesifik model✘Mengubah nilai output_config.effort dapat membatalkan blok pesan, dan pada beberapa model juga cache alat dan sistem (lihat Pemikiran dan caching prompt). Mengatur effort secara eksplisit ke nilai default model setara dengan menghilangkannya dan tidak membatalkan cache. Pada model yang mendukung effort per pesan, perubahan effort yang dibawa dalam pesan role: "system" di dalam messages membiarkan prefiks yang di-cache tetap utuh.
Hasil non-alat yang diteruskan ke permintaan dengan pemikiran✓✓Spesifik modelPada Claude Opus 4.5 dan model Opus yang lebih baru, Claude Sonnet 4.6 dan model Sonnet yang lebih baru, Claude Haiku 5.5, serta setiap model Claude Fable dan Claude Mythos, blok pemikiran dipertahankan secara default, sehingga cache tetap valid (✓). Pada model lain, semua blok pemikiran yang sebelumnya di-cache dihapus dari konteks, dan pesan apa pun yang mengikuti blok pemikiran tersebut dihapus dari cache (✘). Untuk detail lebih lanjut, lihat Caching dengan blok pemikiran.
Blok pemikiran yang tidak disertakan✓✓✘Ketika API tidak menyertakan blok pemikiran yang tidak dipertahankan pada permintaan tersebut, prefiks yang di-cache berubah mulai dari posisi blok tersebut dan seterusnya pada permintaan tersebut. Blok yang dapat dibaca oleh model penerima, yang diteruskan kembali tanpa perubahan, menjaga cache tetap utuh.

Pada model yang mendukung perubahan alat di tengah percakapan, header beta inline-tools-2026-09-15 memungkinkan Anda menambahkan alat, atau mengubah definisi alat, di tengah percakapan tanpa mengedit tools. Kirim definisi dalam blok tool_addition di pesan sistem di tengah percakapan dan biarkan tools persis seperti yang pertama kali Anda kirim. Prefiks yang di-cache tetap cocok, sehingga hanya pesan yang ditambahkan yang diproses sebagai input baru. Satu-satunya pengecualian adalah array tools tanpa alat non-deferred, di mana alat pertama yang didefinisikan dengan cara ini menyebabkan satu cache miss penuh pada permintaan tersebut. Lihat Mendefinisikan alat dalam pesan.

Melacak kinerja cache

Pantau kinerja cache menggunakan field respons API berikut, di dalam usage pada respons (atau event message_start jika menggunakan streaming):

  • cache_creation_input_tokens: Jumlah token yang ditulis ke cache saat membuat entri baru
  • cache_read_input_tokens: Jumlah token yang diambil dari cache untuk permintaan ini
  • input_tokens: Jumlah token input yang tidak dibaca dari atau digunakan untuk membuat cache (yaitu, token setelah breakpoint cache terakhir)

Caching dengan blok pemikiran

Saat menggunakan pemikiran dengan caching prompt, blok pemikiran memiliki perilaku khusus:

Caching otomatis bersama konten lain: Meskipun blok pemikiran tidak dapat ditandai secara eksplisit dengan cache_control, blok tersebut di-cache sebagai bagian dari konten permintaan saat Anda melakukan panggilan API berikutnya dengan hasil alat. Ini umumnya terjadi selama penggunaan alat saat Anda meneruskan blok pemikiran kembali untuk melanjutkan percakapan.

Penghitungan token input: Saat blok pemikiran dibaca dari cache, blok tersebut dihitung sebagai token input dalam metrik penggunaan Anda. Ini penting untuk perhitungan biaya dan penganggaran token.

Pola pembatalan cache:

  • Cache tetap valid saat hanya hasil alat yang diberikan sebagai pesan pengguna.
  • Pada Claude Opus 4.5 dan model Opus yang lebih baru, Claude Sonnet 4.6 dan model Sonnet yang lebih baru, Claude Haiku 5.5, serta setiap model Claude Fable dan Claude Mythos, blok pemikiran dipertahankan secara default bahkan saat konten pengguna yang bukan hasil alat ditambahkan, sehingga cache tetap valid.
  • Pada model lain, menambahkan konten pengguna yang bukan hasil alat membatalkan cache dan menghapus semua blok pemikiran sebelumnya dari konteks.
  • Perilaku caching ini terjadi bahkan tanpa penanda cache_control eksplisit.

Untuk detail lebih lanjut tentang pembatalan cache, lihat Apa yang membatalkan cache.

Contoh dengan penggunaan alat:

Request 1: User: "What's the weather in Paris?"
Response: [thinking_block_1] + [tool_use block 1]

Request 2:
User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True]
Response: [thinking_block_2] + [text block 2]
# Request 2 caches its request content (not the response)
# The cache includes: user message, thinking_block_1, tool_use block 1, and tool_result_1

Request 3:
User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True],
Assistant: [thinking_block_2] + [text block 2],
User: [Text response, cache=True]
# Depending on the model, this non-tool-result user block either keeps prior thinking blocks or strips them (see the next paragraph)

Pada model yang mempertahankan pemikiran sebelumnya, blok pemikiran sebelumnya tetap berada dalam konteks secara default dan tetap menjadi bagian dari prefiks yang di-cache. Pada model lain, semua blok pemikiran sebelumnya dihapus dari konteks pada titik ini.

Untuk informasi lebih rinci, lihat Pemikiran dan caching prompt.

Penyimpanan dan berbagi cache

  • Isolasi organisasi dan workspace: Cache diisolasi antar organisasi. Organisasi yang berbeda tidak pernah berbagi cache, bahkan jika mereka menggunakan prompt yang identik. Cache juga diisolasi per workspace dalam suatu organisasi di Claude API, Claude Platform on AWS, dan Microsoft Foundry; Claude Models on Google Cloud (Google managed) dan Bedrock hanya menggunakan isolasi tingkat organisasi.

  • Pencocokan persis: Cache hit memerlukan segmen prompt yang 100 persen identik, termasuk semua teks dan gambar hingga dan termasuk blok yang ditandai dengan kontrol cache.

  • Pembuatan token output: Caching prompt tidak berpengaruh pada pembuatan token output. Respons yang Anda terima identik dengan yang akan Anda dapatkan jika caching prompt tidak digunakan.

Praktik terbaik untuk caching yang efektif

Untuk mengoptimalkan kinerja caching prompt:

  • Mulailah dengan caching otomatis untuk percakapan multi-giliran. Caching otomatis menangani pengelolaan breakpoint secara otomatis.
  • Gunakan breakpoint tingkat blok eksplisit saat Anda perlu meng-cache bagian berbeda dengan frekuensi perubahan berbeda.
  • Cache konten yang stabil dan dapat digunakan kembali seperti instruksi sistem, informasi latar belakang, konteks besar, atau definisi alat yang sering digunakan.
  • Tempatkan konten yang di-cache di awal prompt untuk kinerja terbaik.
  • Gunakan cache breakpoint secara strategis untuk memisahkan bagian prefiks berbeda yang dapat di-cache.
  • Tempatkan breakpoint pada blok terakhir yang tetap identik di seluruh permintaan. Untuk prompt dengan prefiks statis dan sufiks yang bervariasi (timestamp, konteks per permintaan, pesan yang masuk), itu adalah akhir prefiks, bukan blok yang bervariasi.
  • Analisis tingkat cache hit secara teratur dan sesuaikan strategi Anda sesuai kebutuhan.

Mengoptimalkan untuk berbagai kasus penggunaan

Sesuaikan strategi caching prompt Anda dengan skenario Anda:

  • Agen percakapan: Kurangi biaya dan latensi untuk percakapan panjang, terutama yang memiliki instruksi panjang atau dokumen yang diunggah.
  • Asisten coding: Tingkatkan auto-complete dan tanya jawab basis kode dengan menyimpan bagian yang relevan atau versi ringkasan basis kode dalam prompt.
  • Pemrosesan dokumen besar: Sertakan materi bentuk panjang yang lengkap termasuk gambar dalam prompt Anda tanpa meningkatkan latensi respons.
  • Set instruksi terperinci: Bagikan daftar instruksi, prosedur, dan contoh yang ekstensif untuk menyempurnakan respons Claude. Developer sering menyertakan satu atau dua contoh dalam prompt, tetapi dengan caching prompt Anda bisa mendapatkan kinerja yang lebih baik lagi dengan menyertakan 20+ contoh beragam dari jawaban berkualitas tinggi.
  • Penggunaan alat agentik: Tingkatkan kinerja untuk skenario yang melibatkan banyak panggilan alat dan perubahan kode iteratif, di mana setiap langkah biasanya memerlukan panggilan API baru.
  • Buku, makalah, dokumentasi, transkrip podcast, dan konten bentuk panjang lainnya: Jadikan basis pengetahuan apa pun interaktif dengan menyematkan seluruh dokumen ke dalam prompt, dan biarkan pengguna mengajukan pertanyaan.

Memecahkan masalah umum

Jika Anda mengalami perilaku yang tidak terduga:

  • Pastikan bagian yang di-cache identik di seluruh panggilan. Untuk breakpoint eksplisit, verifikasi bahwa penanda cache_control berada di lokasi yang sama.
  • Periksa bahwa panggilan dilakukan dalam masa hidup cache (5 menit secara default).
  • Verifikasi bahwa tool_choice, penggunaan gambar, konfigurasi pemikiran, dan output_config.effort tetap konsisten antar panggilan.
  • Validasi bahwa Anda meng-cache setidaknya jumlah token minimum untuk model dan platform Anda (lihat Batasan cache).
  • Pastikan breakpoint Anda berada pada blok yang tetap identik di seluruh permintaan. Penulisan cache hanya terjadi di breakpoint, dan jika blok tersebut berubah (timestamp, konteks per permintaan, pesan yang masuk), hash prefiks tidak akan pernah cocok. Lookback tidak menemukan konten stabil di belakang breakpoint; lookback hanya menemukan entri yang ditulis oleh permintaan sebelumnya di breakpoint mereka sendiri.
  • Verifikasi bahwa kunci dalam blok konten tool_use Anda memiliki urutan yang stabil karena beberapa bahasa (misalnya, Swift, Go) mengacak urutan kunci selama konversi JSON, sehingga merusak cache.
  • Gunakan diagnostik cache agar API membandingkan permintaan berturut-turut dan melaporkan bagian prompt mana yang menyimpang.

Durasi cache 1 jam

Jika Anda merasa 5 menit terlalu singkat, Anthropic juga menawarkan durasi cache 1 jam dengan biaya tambahan (lihat Harga).

Untuk menggunakan cache yang diperpanjang, sertakan ttl dalam definisi cache_control seperti ini:

"cache_control": {
  "type": "ephemeral",
  "ttl": "1h"
}

Respons menyertakan informasi cache terperinci seperti berikut:

Output
{
  "usage": {
    "input_tokens": 2048,
    "cache_read_input_tokens": 1800,
    "cache_creation_input_tokens": 248,
    "output_tokens": 503,

    "cache_creation": {
      "ephemeral_5m_input_tokens": 148,
      "ephemeral_1h_input_tokens": 100
    }
  }
}

Field cache_creation_input_tokens sama dengan jumlah nilai dalam objek cache_creation.

Jika Anda melihat penulisan ephemeral_5m_input_tokens yang tidak Anda minta saat menggunakan alat server seperti pencarian web, lihat Hasil alat server di-cache secara otomatis.

Kapan menggunakan cache 1 jam

Jika Anda menggunakan prompt dengan ritme teratur (misalnya, prompt sistem yang Anda kirim lebih sering dari setiap 5 menit), tetap gunakan cache 5 menit, karena cache ini terus diperbarui tanpa biaya tambahan.

Cache 1 jam paling baik digunakan dalam skenario berikut:

  • Saat Anda memiliki prompt yang kemungkinan digunakan lebih jarang dari setiap 5 menit, tetapi lebih sering dari setiap jam. Misalnya, saat side-agent agentik memakan waktu lebih dari 5 menit, atau saat menyimpan percakapan chat panjang dengan pengguna dan Anda umumnya memperkirakan pengguna tersebut mungkin tidak merespons dalam 5 menit ke depan.
  • Saat latensi penting dan prompt lanjutan Anda mungkin dikirim setelah lebih dari 5 menit.
  • Saat Anda ingin meningkatkan pemanfaatan batas laju Anda, karena cache hit tidak dipotong dari batas laju Anda.

Mencampur TTL yang berbeda

Anda dapat menggunakan kontrol cache 1 jam dan 5 menit dalam permintaan yang sama, tetapi dengan batasan penting: Entri cache dengan TTL lebih panjang harus muncul sebelum TTL yang lebih pendek (yaitu, entri cache 1 jam harus muncul sebelum entri cache 5 menit mana pun).

Saat mencampur TTL, Claude API menentukan tiga lokasi penagihan dalam prompt Anda:

  1. Posisi A: Jumlah token pada cache hit terakhir dalam prompt Anda (atau 0 jika tidak ada hit).
    • Cache hit pada entri yang di-cache dengan TTL 5 menit tidak diakui sebagai hit jika blok cache_control dengan TTL 1 jam yang posisinya berada setelah entri tersebut merupakan cache miss.
    • Permintaan yang membaca entri yang di-cache dengan TTL 5 menit memulai ulang masa hidup 5 menit milik entri tersebut, meskipun permintaan tersebut kini mengatur "ttl": "1h".
  2. Posisi B: Jumlah token pada blok cache_control terakhir dengan TTL 1 jam yang posisinya berada setelah A (atau sama dengan A jika tidak ada).
  3. Posisi C: Jumlah token pada blok cache_control terakhir.

Anda akan dikenakan biaya untuk:

  1. Token baca cache untuk A.
  2. Token tulis cache 1 jam untuk (B - A).
  3. Token tulis cache 5 menit untuk (C - B).

Berikut tiga contoh permintaan, yang masing-masing memiliki cache hit dan cache miss yang berbeda. Masing-masing memiliki perhitungan harga yang berbeda, yang ditunjukkan dalam kotak.

Pembacaan cache
Penulisan cache ⁠1h
Penulisan cache ⁠5m
Sisa prompt
hit 1h
(A)
miss 1h
miss 1h
miss 1h
(B)
miss 5m
(C)
Penulisan cache ⁠1h
Penulisan cache ⁠5m
Sisa prompt
(A bernilai nol)
miss 1h
miss 1h
miss 1h
miss 1h
(B)
miss 5m
(C)
Pembacaan cache
Sisa prompt
miss 1h
hit 5m
(A, B, C)

Memanaskan cache terlebih dahulu

“Cache pre-warming” (pemanasan cache terlebih dahulu) memungkinkan Anda memuat prompt sistem atau definisi alat ke dalam cache prompt sebelum pengguna memicu permintaan sebenarnya. Ini dapat mengurangi penalti latensi cache-miss pada interaksi pengguna pertama, sehingga menurunkan “time-to-first-token” (waktu hingga token pertama), atau TTFT, untuk aplikasi yang sensitif terhadap latensi.

Cara kerjanya

Atur max_tokens: 0 dalam permintaan Anda. API membaca prompt Anda ke dalam model dan menulis cache pada setiap breakpoint cache_control, lalu langsung kembali tanpa menghasilkan output apa pun. Respons memiliki array content kosong, stop_reason: "max_tokens", dan blok usage yang terisi lengkap.

Tempatkan breakpoint cache_control pada blok terakhir yang dibagikan dengan permintaan lanjutan (biasanya prompt sistem atau definisi alat Anda), bukan pada pesan pengguna placeholder. Jika tidak, entri cache akan dikunci ke placeholder dan permintaan lanjutan tidak akan mengenainya. Gunakan juga konfigurasi pemikiran dan output_config.effort yang sama dengan permintaan lanjutan Anda: nilai-nilai tersebut dirender ke dalam prompt (lihat Apa yang membatalkan cache), sehingga pemanasan dengan konfigurasi berbeda dapat menulis entri yang tidak pernah dikenai oleh lalu lintas sebenarnya. Ini berarti menggunakan breakpoint cache eksplisit alih-alih caching otomatis, karena caching otomatis menempatkan breakpoint pada blok terakhir, yang di sini adalah placeholder. Pesan pengguna placeholder dapat berupa string apa pun dengan konten non-whitespace (contoh di sini menggunakan "warmup"); kontennya dibaca ke dalam model tetapi tidak pernah dijawab.

client = anthropic.Anthropic()

# Jalankan ini sebelum pengguna datang untuk memanaskan cache prompt sistem bersama.
prewarm = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=0,
    system=[
        {
            "type": "text",
            "text": "You are an expert software engineer with deep knowledge of distributed systems...",
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[{"role": "user", "content": "warmup"}],
)
print(prewarm.stop_reason)  # "max_tokens"
print(prewarm.content)  # []
print(prewarm.usage)

API mengembalikan array content kosong:

Output
{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [],
  "model": "claude-opus-5-5",
  "stop_reason": "max_tokens",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 8,
    "cache_creation_input_tokens": 5120,
    "cache_read_input_tokens": 0,
    "cache_creation": {
      "ephemeral_5m_input_tokens": 5120,
      "ephemeral_1h_input_tokens": 0
    },
    "iterations": [
      {
        "input_tokens": 8,
        "output_tokens": 0,
        "cache_read_input_tokens": 0,
        "cache_creation_input_tokens": 5120,
        "cache_creation": {
          "ephemeral_5m_input_tokens": 5120,
          "ephemeral_1h_input_tokens": 0
        },
        "type": "message"
      }
    ],
    "output_tokens": 0,
    "service_tier": "standard",
    "inference_geo": "global"
  }
}

Pola penggunaan umum

Buat permintaan pemanasan saat aplikasi Anda dimulai (atau pada interval terjadwal), lalu kirim permintaan pengguna sebenarnya setelah pemanasan selesai:

client = anthropic.Anthropic()

SYSTEM_PROMPT = [
    {
        "type": "text",
        "text": "You are an expert software engineer with deep knowledge of distributed systems...",
        "cache_control": {"type": "ephemeral"},
    }
]


def prewarm_cache() -> None:
    """Call this at application startup or on a scheduled interval."""
    client.messages.create(
        model="claude-opus-5-5",
        max_tokens=0,
        system=SYSTEM_PROMPT,
        messages=[{"role": "user", "content": "warmup"}],
    )


def respond(user_message: str) -> anthropic.types.Message:
    """The real user request; benefits from a warm cache."""
    return client.messages.create(
        model="claude-opus-5-5",
        max_tokens=1024,
        system=SYSTEM_PROMPT,
        messages=[{"role": "user", "content": user_message}],
    )


# Panaskan cache sebelum lalu lintas pengguna tiba.
prewarm_cache()

# Nanti, saat pengguna mengirim pesan, prefiks prompt sistem sudah ada di cache.
response = respond("How do I implement a binary search tree?")
for block in response.content:
    if block.type == "text":
        print(block.text)

Perlu diingat bahwa TTL cache tetap berlaku. Untuk cache default 5 menit, kirim permintaan pemanasan baru setidaknya setiap 5 menit agar cache tetap hangat. Untuk jeda yang lebih panjang antar permintaan pengguna, gunakan durasi cache 1 jam sebagai gantinya.

Batasan

Permintaan max_tokens: 0 ditolak dengan invalid_request_error jika salah satu dari hal berikut diatur, karena masing-masing menyiratkan output yang tidak dapat dihasilkan oleh anggaran nol token:

max_tokens: 0 juga ditolak di dalam permintaan Message Batches. Pemanasan menargetkan time-to-first-token, yang tidak berlaku untuk pemrosesan batch, dan entri cache yang ditulis selama pemrosesan batch kemungkinan akan kedaluwarsa sebelum permintaan lanjutan dijalankan.

Mengganti solusi max_tokens=1

Beberapa aplikasi mengirim permintaan max_tokens: 1 untuk memanaskan cache. Utamakan max_tokens: 0 jika permintaan memungkinkannya: tidak ada output yang dihasilkan, sehingga tidak ada balasan satu token yang perlu dibuang, tidak ada token output yang ditagih, dan maksud permintaan menjadi jelas.


Contoh caching prompt

Untuk membantu Anda memulai dengan caching prompt, resep caching prompt di Claude Cookbook menyediakan contoh terperinci dan praktik terbaik.

Cuplikan kode berikut menampilkan berbagai pola caching prompt. Contoh-contoh ini menunjukkan cara mengimplementasikan caching dalam berbagai skenario, membantu Anda memahami aplikasi praktis dari fitur ini:

Retensi data

Caching prompt (baik otomatis maupun eksplisit) memenuhi syarat ZDR. Anthropic tidak menyimpan teks mentah dari prompt Anda atau respons Claude.

Representasi cache KV (key-value) dan hash kriptografis dari konten yang di-cache hanya disimpan di memori dan tidak disimpan secara permanen (at rest). Entri yang di-cache memiliki masa hidup minimum 5 menit (standar) atau 1 jam (diperpanjang), setelah itu entri tersebut dihapus dengan segera, meskipun tidak seketika. Entri cache diisolasi antar organisasi dan, pada Claude API, Claude Platform on AWS, dan Microsoft Foundry, antar workspace dalam satu organisasi.


FAQ

Ketersediaan

Caching prompt
API
  • Messages API
  • Managed Agents Beta
Model
  • Semua model

Endpoint yang berlaku

  • /v1/messages
Retensi data nolLayak

Tidak termasuk Model yang dicakup

Prompt Anda dan output Claude tidak disimpan. Representasi cache KV dan hash kriptografis disimpan di memori selama TTL cache dan segera dihapus setelah kedaluwarsa. Pelajari lebih lanjut

HIPAALayak

Apakah halaman ini membantu?