Caching prompt

"Prompt caching" (caching prompt) mengoptimalkan penggunaan API Anda dengan memungkinkan pemrosesan dilanjutkan dari "prefix" (awalan) 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 panjang. Paling cocok untuk percakapan multi-giliran di mana riwayat pesan yang terus bertambah harus di-cache secara otomatis.
• Breakpoint cache eksplisit: Tempatkan cache_control langsung pada blok konten individual untuk kontrol yang lebih terperinci atas apa saja yang di-cache.

Cara termudah 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 menyimpan ke cache semua konten hingga dan termasuk blok terakhir yang dapat di-cache. Pada permintaan berikutnya dengan prefix 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 prefix 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 menyimpan prefix ke cache 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 tersebut: jika sebuah respons membutuhkan 4 menit untuk di-stream, permintaan lanjutan yang menggunakan kembali prefix yang di-cache yang sama harus dimulai dalam waktu sekitar 1 menit setelah respons tersebut selesai.

Harga

Caching prompt memperkenalkan struktur harga baru. Tabel berikut menunjukkan harga per juta token untuk setiap model yang didukung:

Model	Base tokens		Prompt caching
Name	Input	Output	5m writes	1h writes	Hits and refreshes
Claude Fable 5.1For demanding reasoning and long-horizon agentic work	$10 / MTok	$50 / MTok	$12.50 / MTok	$20 / MTok	$0.25 / MTok1
Claude Opus 5.5For long-running agentic coding and knowledge work	$4 / MTok	$20 / MTok	$5 / MTok	$8 / MTok	$0.20 / MTok2
Claude Sonnet 5.5The best combination of speed and intelligence	$2 / MTok	$10 / MTok	$2.50 / MTok	$4 / MTok	$0.20 / MTok
Claude Haiku 4.5The fastest model with near-frontier intelligence	$1 / MTok	$5 / MTok	$1.25 / MTok	$2 / MTok	$0.10 / MTok
Additional models
Claude Mythos 5.1	$10 / MTok	$50 / MTok	$12.50 / MTok	$20 / MTok	$0.25 / MTok1
Claude Fable 5	$10 / MTok	$50 / MTok	$12.50 / MTok	$20 / MTok	$1 / MTok
Claude Mythos 5	$10 / MTok	$50 / MTok	$12.50 / MTok	$20 / MTok	$1 / MTok
Claude Opus 5	$5 / MTok	$25 / MTok	$6.25 / MTok	$10 / MTok	$0.50 / MTok
Claude Opus 4.8	$5 / MTok	$25 / MTok	$6.25 / MTok	$10 / MTok	$0.50 / MTok
Claude Opus 4.7	$5 / MTok	$25 / MTok	$6.25 / MTok	$10 / MTok	$0.50 / MTok
Claude Opus 4.6	$5 / MTok	$25 / MTok	$6.25 / MTok	$10 / MTok	$0.50 / MTok
Claude Opus 4.5	$5 / MTok	$25 / MTok	$6.25 / MTok	$10 / MTok	$0.50 / MTok
Claude Opus 4.1	$15 / MTok	$75 / MTok	$18.75 / MTok	$30 / MTok	$1.50 / MTok
Claude Opus 4	$15 / MTok	$75 / MTok	$18.75 / MTok	$30 / MTok	$1.50 / MTok
Claude Sonnet 5	$2 / MTok	$10 / MTok	$2.50 / MTok	$4 / MTok	$0.20 / MTok
Claude Sonnet 4.6	$3 / MTok	$15 / MTok	$3.75 / MTok	$6 / MTok	$0.30 / MTok
Claude Sonnet 4.5	$3 / MTok	$15 / MTok	$3.75 / MTok	$6 / MTok	$0.30 / MTok
Claude Sonnet 4	$3 / MTok	$15 / MTok	$3.75 / MTok	$6 / MTok	$0.30 / MTok
Claude Haiku 3.5	$0.80 / MTok	$4 / MTok	$1 / MTok	$1.60 / MTok	$0.08 / MTok

^{1 Cache hits and refreshes on Claude Fable 5.1 and Claude Mythos 5.1 are priced at 0.025x the base input price.}

^{2 Cache hits and refreshes on Claude Opus 5.5 are priced at 0.05x the base input price.}

^{All other models use the standard 0.1x multiplier.}

Model yang didukung

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

Caching otomatis

Caching otomatis adalah cara termudah untuk mengaktifkan caching prompt. 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 panjang. Setiap permintaan baru menyimpan ke cache semua konten hingga blok terakhir yang dapat di-cache, dan konten sebelumnya dibaca dari cache.

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

Dukungan TTL

Secara default, caching otomatis menggunakan "time to live" (masa berlaku), atau TTL, selama 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 menyimpan prompt sistem Anda ke cache, 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 "lookback window" (jendela penelusuran mundur) 20 blok semuanya berlaku sama seperti pada breakpoint eksplisit.

Kasus khusus

• Jika blok terakhir sudah memiliki cache_control eksplisit dengan TTL yang sama, caching otomatis tidak melakukan apa pun.
• Jika blok terakhir memiliki cache_control eksplisit dengan TTL yang berbeda, API mengembalikan error 400.
• Jika sudah ada 4 breakpoint eksplisit tingkat blok, 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 menelusuri mundur untuk menemukan blok terdekat yang memenuhi syarat. Jika tidak ada yang ditemukan, caching dilewati.

Breakpoint cache eksplisit

Untuk kontrol lebih atas caching, Anda dapat menempatkan cache_control langsung pada blok konten individual. Ini berguna ketika Anda perlu menyimpan ke cache bagian-bagian berbeda yang berubah dengan frekuensi berbeda, atau memerlukan kontrol terperinci 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.

Prefix 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 prefix otomatis

Anda dapat menggunakan hanya satu breakpoint cache di akhir konten statis Anda, dan sistem akan secara otomatis menemukan prefix 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 sebuah blok dengan cache_control menulis tepat satu entri cache: hash dari prefix yang berakhir di blok tersebut. Sistem tidak menulis entri untuk posisi sebelumnya mana pun. Karena hash bersifat kumulatif, mencakup semua konten hingga dan termasuk breakpoint, mengubah blok mana pun di atau sebelum breakpoint akan menghasilkan hash yang berbeda pada permintaan berikutnya.

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

3. Lookback window adalah 20 blok. Sistem memeriksa paling banyak 20 posisi per breakpoint, dengan breakpoint itu sendiri dihitung 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 yang berurutan dihitung sebagai satu posisi, demikian pula rangkaian blok tool_result yang berurutan, sehingga satu giliran dengan banyak pemanggilan alat paralel tidak dengan sendirinya mendorong entri permintaan sebelumnya keluar dari jendela.

Contoh: Penelusuran mundur dalam percakapan yang terus bertambah

Anda menambahkan blok baru di setiap giliran dan menetapkan 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 menelusuri mundur ke blok 10 dan menemukan entri dari giliran 1. "Cache hit" (kecocokan cache) terjadi di blok 10; sistem hanya memproses blok 11 hingga 15 sebagai konten baru 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 akan memulai lookback window kedua di sana, yang menemukan entri giliran 2.

Kesalahan umum: Breakpoint pada konten yang berubah di 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 menetapkan cache_control pada blok 6:

• Permintaan 1: Penulisan cache di blok 6. Hash mencakup timestamp.
• Permintaan 2: Timestamp berbeda, sehingga hash prefix di blok 6 berbeda. Penelusuran mundur melewati 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 di setiap permintaan dan tidak pernah mendapatkan pembacaan.

Penelusuran mundur tidak menemukan konten stabil di belakang breakpoint Anda lalu menyimpannya ke cache. Penelusuran ini 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 akan membaca prefix yang di-cache. Caching otomatis juga terjebak dalam masalah yang sama: caching otomatis menempatkan breakpoint pada blok terakhir yang dapat di-cache, yang dalam struktur ini adalah blok yang berubah di setiap permintaan, jadi gunakan breakpoint eksplisit pada blok 5 sebagai gantinya.

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

Kapan menggunakan beberapa breakpoint

Anda dapat menentukan hingga 4 breakpoint cache jika Anda ingin:

• Menyimpan ke cache bagian-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

Breakpoint cache itu sendiri tidak menambah biaya apa pun. Anda hanya dikenakan biaya untuk:

• Penulisan cache: Saat konten baru ditulis ke cache (25% lebih mahal dari token input dasar untuk TTL 5 menit)
• Pembacaan cache: Saat konten yang di-cache digunakan (10% dari harga token input dasar, atau 2,5% pada Claude Fable 5.1 dan Claude Mythos 5.1, dan 5% pada Claude Opus 5.5)
• 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 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, Google Cloud, dan Microsoft Foundry, panjang prompt minimum yang dapat di-cache adalah:

• 512 token untuk Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, Claude Fable 5, dan Claude Mythos 5
• 2.048 token untuk Claude Mythos Preview dan Claude Opus 4.7
• 4.096 token untuk Claude Opus 4.6 dan Claude Opus 4.5
• 1.024 token untuk Claude Opus 4.8, Claude Sonnet 5, Claude Sonnet 4.6, Claude Sonnet 4.5, Claude Opus 4.1 (dihentikan, kecuali di Bedrock dan Google Cloud), Claude Opus 4 (dihentikan, kecuali di Google Cloud), dan Claude Sonnet 4 (dihentikan, kecuali di Bedrock dan Google Cloud)
• 4.096 token untuk Claude Haiku 4.5
• 2.048 token untuk Claude Haiku 3.5 (dihentikan, kecuali di Bedrock dan Google Cloud)

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

Prompt yang lebih pendek tidak dapat di-cache, meskipun ditandai dengan cache_control. Setiap permintaan untuk menyimpan ke cache kurang dari jumlah token ini akan diproses tanpa caching, dan tidak ada error yang dikembalikan. Untuk memverifikasi apakah sebuah prompt di-cache, periksa field usage pada respons: jika cache_creation_input_tokens dan cache_read_input_tokens keduanya bernilai 0, prompt tersebut tidak di-cache (kemungkinan karena tidak memenuhi persyaratan panjang minimum).

Jika prompt Anda sedikit di bawah 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.

Saat ini, "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 mencakup:

• 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 & 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

Masing-masing elemen ini dapat di-cache, baik secara otomatis maupun dengan menandainya menggunakan cache_control.

Apa yang tidak dapat di-cache

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

• Blok thinking tidak dapat di-cache secara langsung dengan cache_control. Namun, blok thinking DAPAT di-cache bersama konten lain ketika muncul di giliran asisten sebelumnya. Ketika 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, simpan blok tingkat teratas ke cache.

  Dalam kasus kutipan, blok konten dokumen tingkat teratas yang berfungsi sebagai materi sumber untuk kutipan dapat di-cache. Ini memungkinkan Anda menggunakan caching prompt dengan kutipan secara efektif dengan menyimpan ke cache dokumen-dokumen yang akan direferensikan 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.

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 tersebut dalam blok tool_addition di dalam pesan sistem di tengah percakapan dan biarkan tools persis seperti saat pertama kali Anda mengirimnya. Prefix 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 performa cache

Pantau performa 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 thinking

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

Caching otomatis bersama konten lain: Meskipun blok thinking 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 ketika Anda mengirim kembali blok thinking untuk melanjutkan percakapan.

Penghitungan token input: Ketika blok thinking 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 ketika hanya hasil alat yang diberikan sebagai pesan pengguna
• Pada Opus 4.5+ dan Sonnet 4.6+, blok thinking dipertahankan secara default bahkan ketika konten pengguna yang bukan hasil alat ditambahkan, sehingga cache tetap valid
• Pada model Opus/Sonnet sebelumnya dan semua model Haiku, cache dibatalkan ketika konten pengguna yang bukan hasil alat ditambahkan, menyebabkan semua blok thinking sebelumnya dihapus 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]
# On earlier Opus/Sonnet and all Haiku models, non-tool-result user block causes prior thinking blocks to be stripped; on Opus 4.5+/Sonnet 4.6+ they are kept

Pada model Opus/Sonnet sebelumnya dan semua model Haiku, semua blok thinking sebelumnya dihapus dari konteks pada titik ini. Pada Opus 4.5+ dan Sonnet 4.6+, blok thinking sebelumnya dipertahankan secara default dan tetap menjadi bagian dari prefix yang di-cache.

Untuk informasi lebih terperinci, lihat Thinking 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 satu organisasi pada Claude API, Claude Platform on AWS, dan Microsoft Foundry; Bedrock dan Google Cloud hanya menggunakan isolasi tingkat organisasi.

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

• 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 performa caching prompt:

• Mulailah dengan caching otomatis untuk percakapan multi-giliran. Caching otomatis menangani pengelolaan breakpoint secara otomatis.
• Gunakan breakpoint eksplisit tingkat blok ketika Anda perlu menyimpan ke cache bagian-bagian berbeda dengan frekuensi perubahan yang berbeda.
• Simpan ke 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 performa terbaik.
• Gunakan breakpoint cache secara strategis untuk memisahkan bagian-bagian prefix yang dapat di-cache.
• Tempatkan breakpoint pada blok terakhir yang tetap identik di seluruh permintaan. Untuk prompt dengan prefix statis dan sufiks yang bervariasi (timestamp, konteks per permintaan, pesan yang masuk), itu adalah akhir prefix, bukan blok yang bervariasi.
• Analisis tingkat cache hit secara berkala dan sesuaikan strategi Anda sesuai kebutuhan.

Mengoptimalkan untuk berbagai kasus penggunaan

Sesuaikan strategi caching prompt Anda dengan skenario Anda:

• Agen percakapan: Kurangi biaya dan "latency" (latensi) untuk percakapan panjang, terutama yang memiliki instruksi panjang atau dokumen yang diunggah.
• Asisten coding: Tingkatkan autocomplete dan tanya jawab basis kode dengan menyimpan bagian-bagian yang relevan atau versi ringkasan basis kode dalam prompt.
• Pemrosesan dokumen besar: Sertakan materi panjang yang lengkap termasuk gambar dalam prompt Anda tanpa meningkatkan latensi respons.
• Kumpulan 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 performa yang lebih baik lagi dengan menyertakan 20+ contoh beragam dari jawaban berkualitas tinggi.
• Penggunaan alat agentik: Tingkatkan performa untuk skenario yang melibatkan banyak pemanggilan alat dan perubahan kode iteratif, di mana setiap langkah biasanya memerlukan panggilan API baru.
• Berbicara dengan buku, makalah, dokumentasi, transkrip podcast, dan konten panjang lainnya: Hidupkan basis pengetahuan apa pun dengan menyematkan seluruh dokumen ke dalam prompt, dan biarkan pengguna mengajukan pertanyaan kepadanya.

Memecahkan masalah umum

Jika 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 thinking, dan output_config.effort tetap konsisten antar panggilan
• Validasi bahwa Anda menyimpan ke 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 prefix tidak akan pernah cocok. Penelusuran mundur tidak menemukan konten stabil di belakang breakpoint; penelusuran ini 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 yang berurutan 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.

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:

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

Perhatikan bahwa field cache_creation_input_tokens saat ini 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 Penggunaan alat dengan caching prompt.

Kapan menggunakan cache 1 jam

Jika Anda memiliki prompt yang digunakan secara teratur (yaitu, prompt sistem yang digunakan lebih sering dari setiap 5 menit), tetap gunakan cache 5 menit, karena cache ini akan terus diperbarui tanpa biaya tambahan.

Cache 1 jam paling baik digunakan dalam skenario berikut:

• Ketika Anda memiliki prompt yang kemungkinan digunakan lebih jarang dari 5 menit, tetapi lebih sering dari setiap jam. Misalnya, ketika agen sampingan agentik akan membutuhkan waktu lebih dari 5 menit, atau ketika menyimpan percakapan chat panjang dengan pengguna dan Anda umumnya memperkirakan pengguna tersebut mungkin tidak merespons dalam 5 menit ke depan.
• Ketika latensi penting dan prompt lanjutan Anda mungkin dikirim setelah lebih dari 5 menit.
• Ketika Anda ingin meningkatkan pemanfaatan batas laju Anda, karena cache hit tidak dikurangkan dari batas laju Anda.

Mencampur TTL yang berbeda

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

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

1. Posisi A: Jumlah token pada "cache hit" (kecocokan cache) tertinggi (atau 0 jika tidak ada hit).
2. Posisi B: Jumlah token pada blok cache_control 1 jam tertinggi 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. Gambar ini menunjukkan token input dari 3 permintaan, yang masing-masing memiliki cache hit dan cache miss yang berbeda. Akibatnya, masing-masing memiliki perhitungan harga yang berbeda, yang ditampilkan dalam kotak berwarna.

Memanaskan cache terlebih dahulu

"Cache pre-warming" (pemanasan awal cache) memungkinkan Anda memuat prompt sistem atau definisi alat ke dalam cache prompt sebelum pengguna memicu permintaan sebenarnya. Ini menghilangkan penalti "latency" (latensi) akibat cache miss pada interaksi pengguna pertama, sehingga mengurangi "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 segera kembali tanpa menghasilkan output apa pun. Respons memiliki array content yang kosong, stop_reason: "max_tokens", dan blok usage yang terisi lengkap.

Tempatkan breakpoint cache_control pada blok terakhir yang digunakan bersama 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 thinking dan output_config.effort yang sama dengan permintaan lanjutan Anda: nilai-nilai tersebut dirender ke dalam prompt (lihat Apa yang membatalkan cache), sehingga pemanasan awal dengan konfigurasi berbeda dapat menulis entri yang tidak pernah dikenai oleh lalu lintas Anda yang sebenarnya. Ini berarti menggunakan breakpoint cache eksplisit alih-alih caching otomatis, karena caching otomatis menempatkan breakpoint pada blok terakhir, yang dalam kasus ini adalah placeholder. Pesan pengguna placeholder dapat berupa string apa pun dengan konten yang bukan spasi kosong (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 yang kosong:

{
  "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

Kirim permintaan pemanasan awal saat aplikasi Anda dimulai (atau pada interval terjadwal), lalu kirim permintaan pengguna yang sebenarnya setelah pemanasan awal 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 masuk.
prewarm_cache()

# Nantinya, 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 awal baru setidaknya setiap 5 menit agar cache tetap hangat. Untuk jeda yang lebih panjang antar permintaan pengguna, gunakan durasi cache 1 jam sebagai gantinya.

Keterbatasan

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 dengan anggaran nol token:

• stream: true
• Pemikiran diperpanjang (thinking.type: "enabled")
• Output terstruktur (output_config.format)
• tool_choice berupa {"type": "tool", ...} atau {"type": "any"}

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

Mengganti solusi sementara max_tokens=1

Sebelum max_tokens: 0 tersedia, beberapa aplikasi menggunakan panggilan pemanasan max_tokens: 1 untuk mencapai efek yang sama. Pendekatan max_tokens: 0 lebih disarankan: 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 "prompt caching" (caching prompt), cookbook caching prompt 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 penerapan praktis fitur ini:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "You are an AI assistant tasked with analyzing legal documents.",
        },
        {
            "type": "text",
            "text": "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]",
            "cache_control": {"type": "ephemeral"},
        },
    ],
    messages=[
        {
            "role": "user",
            "content": "What are the key terms and conditions in this agreement?",
        }
    ],
)
print(response.usage.model_dump_json())

{
  "model": "claude-opus-5-5",
  "max_tokens": 1024,
  "tools": [
    {
      "name": "get_weather",
      "description": "Get the current weather in a given location",
      "input_schema": {
        "type": "object",
        "properties": { "location": { "type": "string" } },
        "required": ["location"]
      }
    },
    {
      "name": "get_time",
      "description": "Get the current time in a given time zone",
      "input_schema": {
        "type": "object",
        "properties": { "timezone": { "type": "string" } },
        "required": ["timezone"]
      },
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [{ "role": "user", "content": "What is the weather and time in New York?" }]
}

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "...long system prompt",
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[
        # ...percakapan panjang sejauh ini
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Hello, can you tell me more about the solar system?",
                }
            ],
        },
        {
            "role": "assistant",
            "content": "Certainly! The solar system is the collection of celestial bodies that orbit our Sun. It consists of eight planets, numerous moons, asteroids, comets, and other objects. The planets, in order from closest to farthest from the Sun, are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune. Each planet has its own unique characteristics and features. Is there a specific aspect of the solar system you'd like to know more about?",
        },
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Good to know."},
                {
                    "type": "text",
                    "text": "Tell me more about Mars.",
                    "cache_control": {"type": "ephemeral"},
                },
            ],
        },
    ],
)
print(response.usage.model_dump_json())

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    tools=[
        {
            "name": "search_documents",
            "description": "Search through the knowledge base",
            "input_schema": {
                "type": "object",
                "properties": {
                    "query": {"type": "string", "description": "Search query"}
                },
                "required": ["query"],
            },
        },
        {
            "name": "get_document",
            "description": "Retrieve a specific document by ID",
            "input_schema": {
                "type": "object",
                "properties": {
                    "doc_id": {"type": "string", "description": "Document ID"}
                },
                "required": ["doc_id"],
            },
            "cache_control": {"type": "ephemeral"},
        },
    ],
    system=[
        {
            "type": "text",
            "text": "You are a helpful research assistant with access to a document knowledge base.\n\n# Instructions\n- Always search for relevant documents before answering\n- Provide citations for your sources\n- Be objective and accurate in your responses\n- If multiple documents contain relevant information, synthesize them\n- Acknowledge when information is not available in the knowledge base",
            "cache_control": {"type": "ephemeral"},
        },
        {
            "type": "text",
            "text": "# Knowledge Base Context\n\nHere are the relevant documents for this conversation:\n\n## Document 1: Solar System Overview\nThe solar system consists of the Sun and all objects that orbit it...\n\n## Document 2: Planetary Characteristics\nEach planet has unique features. Mercury is the smallest planet...\n\n## Document 3: Mars Exploration\nMars has been a target of exploration for decades...\n\n[Additional documents...]",
            "cache_control": {"type": "ephemeral"},
        },
    ],
    messages=[
        {
            "role": "user",
            "content": "Can you search for information about Mars rovers?",
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "tool_use",
                    "id": "tool_1",
                    "name": "search_documents",
                    "input": {"query": "Mars rovers"},
                }
            ],
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "tool_1",
                    "content": "Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)",
                }
            ],
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document.",
                }
            ],
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Yes, please tell me about the Perseverance rover specifically.",
                    "cache_control": {"type": "ephemeral"},
                }
            ],
        },
    ],
)
print(response.usage.model_dump_json())

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 berlaku 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.

Untuk kelayakan ZDR di semua fitur, lihat API dan retensi data.

FAQ

total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens

client.beta.prompt_caching.messages.create(**params)

client.messages.create(**params)

client.beta.promptCaching.messages.create(/* ... */);

client.messages.create(/* ... */);