Caching prompt

"Prompt caching" (caching prompt) mengoptimalkan penggunaan API Anda dengan memungkinkan 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 atas permintaan Anda. Sistem secara otomatis menerapkan cache breakpoint ke blok terakhir yang dapat di-cache dan memindahkannya ke depan seiring percakapan berkembang. 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 yang di-cache.

Cara paling sederhana untuk memulai adalah dengan caching otomatis:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-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

Ketika Anda mengirim permintaan dengan caching prompt diaktifkan:

1. Sistem memeriksa apakah prefiks prompt, hingga cache breakpoint yang ditentukan, sudah di-cache dari kueri terbaru.
2. Jika ditemukan, sistem menggunakan versi yang di-cache, mengurangi waktu pemrosesan dan biaya.
3. Jika tidak, sistem memproses prompt lengkap dan meng-cache prefiks tersebut begitu 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.



Harga

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



Model yang didukung

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



Caching otomatis

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-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 berkembang. Setiap permintaan baru meng-cache semuanya hingga blok terakhir yang dapat di-cache, dan konten sebelumnya dibaca dari cache.

Cache breakpoint secara otomatis berpindah ke blok terakhir yang dapat di-cache pada setiap permintaan, sehingga Anda tidak perlu memperbarui penanda cache_control apa pun seiring percakapan berkembang.



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 cache breakpoint eksplisit. Ketika digunakan bersama, cache breakpoint 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",
  "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 dengan breakpoint eksplisit.



Kasus khusus

• Jika blok terakhir sudah memiliki cache_control eksplisit dengan TTL yang sama, caching otomatis tidak melakukan apa-apa (no-op).
• Jika blok terakhir memiliki cache_control eksplisit dengan TTL yang berbeda, API mengembalikan error 400.
• Jika 4 breakpoint tingkat blok eksplisit sudah ada, API mengembalikan error 400 (tidak ada slot tersisa untuk caching otomatis).
• Jika blok terakhir tidak memenuhi syarat sebagai target cache breakpoint 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 besar atas caching, Anda dapat menempatkan cache_control langsung pada blok konten individual. Ini berguna ketika Anda perlu meng-cache bagian berbeda yang berubah pada frekuensi berbeda, atau memerlukan kontrol yang lebih rinci atas apa yang di-cache.



Menyusun prompt Anda

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

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



Cara kerja pemeriksaan prefiks otomatis

Anda dapat menggunakan hanya satu cache breakpoint di akhir konten statis Anda, dan sistem akan 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 sebuah blok dengan cache_control menulis tepat satu entri cache: hash dari prefiks yang berakhir di blok tersebut. Sistem tidak menulis entri untuk posisi mana pun 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 yang lebih awal 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 per breakpoint, 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).

Contoh: Lookback dalam percakapan yang berkembang

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

• Giliran 1: 10 blok, breakpoint pada blok 10. Tidak ada entri cache sebelumnya. Sistem menulis entri di blok 10.
• Giliran 2: 15 blok, breakpoint pada blok 15. Blok 15 tidak memiliki entri, jadi sistem berjalan mundur ke blok 10 dan menemukan entri giliran-1. Cache hit di blok 10; sistem hanya memproses blok 11 hingga 15 secara 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, jadi 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 menetapkan cache_control pada blok 6:

• Permintaan 1: Penulisan cache di blok 6. Hash mencakup timestamp.
• Permintaan 2: Timestamp berbeda, jadi 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 dan 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 mengalami jebakan 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 berkembang, 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 masuk), tempatkan breakpoint di akhir prefiks statis, bukan pada blok yang bervariasi.



Kapan menggunakan beberapa breakpoint

Anda dapat mendefinisikan hingga 4 cache breakpoint jika Anda ingin:

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



Memahami biaya cache breakpoint

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

• Penulisan cache: Ketika konten baru ditulis ke cache (25% lebih banyak dari token input dasar untuk TTL 5 menit)
• Pembacaan cache: Ketika konten yang di-cache digunakan (10% dari harga token input dasar)
• 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, Google Cloud, dan Microsoft Foundry, panjang prompt minimum yang dapat di-cache adalah:

• 512 token untuk Claude Opus 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 (tidak digunakan lagi), Claude Opus 4 (dipensiunkan, kecuali di Google Cloud), dan Claude Sonnet 4 (dipensiunkan, kecuali di Bedrock dan Google Cloud)
• 4.096 token untuk Claude Haiku 4.5
• 2.048 token untuk Claude Haiku 3.5 (dipensiunkan, kecuali di Google Cloud)

Minimum ini berlaku di setiap platform tempat masing-masing 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 akan diproses tanpa caching, dan tidak ada error yang dikembalikan. Untuk memverifikasi apakah sebuah prompt di-cache, periksa 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 di bawah minimum untuk model dan platform Anda, memperluas konten yang di-cache untuk mencapai ambang batas sering kali sepadan. Pembacaan cache berbiaya jauh lebih rendah daripada token input yang tidak di-cache, jadi mencapai minimum dapat mengurangi biaya untuk prompt yang sering digunakan kembali.

Untuk permintaan bersamaan, perhatikan bahwa entri cache hanya 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 tipe 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 user maupun assistant
• Gambar & Dokumen: Blok konten dalam array messages.content, dalam giliran user
• Penggunaan alat dan hasil alat: Blok konten dalam array messages.content, dalam giliran user maupun assistant

Setiap elemen ini dapat di-cache, baik secara otomatis maupun dengan menandainya dengan 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 assistant sebelumnya. Ketika di-cache dengan cara ini, blok tersebut DIHITUNG sebagai token input ketika dibaca dari cache.

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

  Dalam kasus citations, blok konten dokumen tingkat atas yang berfungsi sebagai materi sumber untuk citations dapat di-cache. Ini memungkinkan Anda menggunakan caching prompt dengan citations secara efektif dengan meng-cache dokumen yang akan direferensikan oleh citations.

• 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, sementara ✓ menunjukkan bahwa cache tetap valid.



Melacak kinerja cache

Pantau kinerja cache menggunakan field respons API berikut, di dalam usage dalam 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 cache breakpoint terakhir).

total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens



Caching dengan blok thinking

Ketika 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 ketika Anda melakukan panggilan API berikutnya dengan hasil alat. Ini umumnya terjadi selama penggunaan alat ketika Anda meneruskan blok thinking kembali untuk melanjutkan percakapan.

Penghitungan token input: Ketika blok thinking dibaca dari cache, blok tersebut dihitung sebagai token input dalam metrik usage Anda. Ini penting untuk perhitungan biaya dan penganggaran token.

Pola pembatalan cache:

• Cache tetap valid ketika hanya hasil alat yang diberikan sebagai pesan user
• Pada Opus 4.5+ dan Sonnet 4.6+, blok thinking dipertahankan secara default bahkan ketika konten user non-hasil-alat ditambahkan, sehingga cache tetap valid
• Pada model Opus/Sonnet yang lebih lama dan semua model Haiku, cache dibatalkan ketika konten user non-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 yang lebih lama 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 prefiks yang di-cache.

Untuk informasi lebih rinci, lihat Thinking dan caching prompt.



Penyimpanan dan pembagian cache

• Isolasi organisasi dan workspace: Cache diisolasi antar organisasi. Organisasi yang berbeda tidak pernah berbagi cache, bahkan jika mereka menggunakan prompt yang identik. Mulai 5 Februari 2026, cache juga diisolasi per workspace dalam sebuah organisasi pada Claude API, Claude Platform on AWS, dan Microsoft Foundry; Bedrock dan Google Cloud terus menggunakan isolasi tingkat organisasi saja.

• 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 apa 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. Ini menangani manajemen breakpoint secara otomatis.
• Gunakan breakpoint tingkat blok eksplisit ketika Anda perlu meng-cache bagian berbeda dengan frekuensi perubahan yang 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 yang dapat di-cache yang berbeda.
• 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 masuk), itu adalah akhir dari 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 yang diperpanjang, terutama yang memiliki instruksi panjang atau dokumen yang diunggah.
• Asisten pengkodean: Tingkatkan autocomplete dan tanya jawab codebase dengan menyimpan bagian yang relevan atau versi ringkasan dari codebase dalam prompt.
• Pemrosesan dokumen besar: Masukkan materi panjang 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. Pengembang sering menyertakan satu atau dua contoh dalam prompt, tetapi dengan caching prompt Anda bisa mendapatkan kinerja yang lebih baik dengan menyertakan 20+ contoh jawaban berkualitas tinggi yang beragam.
• Penggunaan alat agentik: Tingkatkan kinerja untuk skenario yang melibatkan beberapa panggilan 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 membiarkan pengguna mengajukan pertanyaan kepadanya.



Pemecahan 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 meng-cache setidaknya jumlah token minimum untuk model dan platform Anda (lihat Batasan cache)
• Konfirmasikan 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 masuk), hash prefiks tidak 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, yang merusak cache
• Gunakan diagnostik cache agar API membandingkan permintaan berurutan dan melaporkan bagian mana dari prompt 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 mencakup 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 dengan irama teratur (yaitu, prompt sistem yang digunakan lebih sering dari setiap 5 menit), terus gunakan cache 5 menit, karena ini akan terus diperbarui tanpa biaya tambahan.

Cache 1 jam paling baik digunakan dalam skenario berikut:

• Ketika Anda memiliki prompt yang kemungkinan digunakan kurang sering dari 5 menit, tetapi lebih sering dari setiap jam. Misalnya, ketika side-agent agentik akan memakan 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 berikutnya.
• Ketika latensi penting dan prompt lanjutan Anda mungkin dikirim lebih dari 5 menit kemudian.
• 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 batasan penting: Entri cache dengan TTL yang lebih panjang harus muncul sebelum TTL yang lebih pendek (yaitu, entri cache 1 jam harus muncul sebelum entri cache 5 menit mana pun).

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

1. Posisi A: Jumlah token pada cache hit 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 pembacaan cache untuk A.
2. Token penulisan cache 1 jam untuk (B - A).
3. Token penulisan cache 5 menit untuk (C - B).

Berikut tiga contoh. Ini menggambarkan token input dari 3 permintaan, yang masing-masing memiliki cache hit dan cache miss yang berbeda. Masing-masing memiliki harga terhitung yang berbeda, ditunjukkan dalam kotak berwarna, sebagai hasilnya.



Pra-pemanasan cache

Pra-pemanasan cache (cache pre-warming) memungkinkan Anda memuat prompt sistem atau definisi alat Anda ke dalam cache prompt sebelum pengguna memicu permintaan nyata. Ini menghilangkan penalti latensi cache-miss pada interaksi pengguna pertama, mengurangi time-to-first-token (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 mengembalikan respons tanpa menghasilkan output apa pun. Respons memiliki array content kosong, stop_reason: "max_tokens", dan blok usage yang terisi penuh.

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 thinking dan output_config.effort yang sama dengan permintaan lanjutan Anda: nilai-nilai tersebut dirender ke dalam prompt (lihat Apa yang membatalkan cache), sehingga pre-warm dengan konfigurasi yang berbeda dapat menulis entri yang tidak pernah dikenai oleh lalu lintas nyata Anda. Ini berarti menggunakan breakpoint cache eksplisit alih-alih caching otomatis, karena caching otomatis menempatkan breakpoint pada blok terakhir, yang dalam hal ini 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",
    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:

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [],
  "model": "claude-opus-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 pre-warm saat aplikasi Anda dimulai (atau pada interval terjadwal), lalu kirim permintaan pengguna yang sebenarnya setelah pre-warm 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",
        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",
        max_tokens=1024,
        system=SYSTEM_PROMPT,
        messages=[{"role": "user", "content": user_message}],
    )


# Panaskan cache sebelum ada lalu lintas pengguna yang masuk.
prewarm_cache()

# Nantinya, saat pengguna mengirim pesan, prefiks prompt sistem sudah ter-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 pre-warm baru setidaknya setiap 5 menit untuk menjaga cache tetap hangat. Untuk jeda yang lebih lama antara permintaan pengguna, gunakan durasi cache 1 jam sebagai gantinya.



Keterbatasan

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

• stream: true
• Pemikiran diperpanjang (thinking.type: "enabled")
• Structured outputs (output_config.format)
• tool_choice dengan nilai {"type": "tool", ...} atau {"type": "any"}

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



Menggantikan solusi sementara max_tokens=1

Sebelum max_tokens: 0 tersedia, beberapa aplikasi menggunakan panggilan warm-up 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 dari permintaan tersebut tidak ambigu.



Contoh caching prompt

Untuk membantu Anda memulai dengan 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 skenario yang berbeda, membantu Anda memahami penerapan 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 dalam memori dan tidak disimpan secara permanen. Entri yang di-cache memiliki masa hidup minimum 5 menit (standar) atau 1 jam (diperpanjang), setelah itu entri tersebut segera, meskipun tidak seketika, dihapus. Entri cache diisolasi antar organisasi dan, pada Claude API, Claude Platform di AWS, dan Microsoft Foundry, antar workspace dalam suatu organisasi.

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



FAQ