Caching prompt

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 breakpoint cache 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.
• Breakpoint cache eksplisit: Tempatkan cache_control langsung pada blok konten individual untuk kontrol yang lebih detail atas apa yang di-cache.

Cara paling sederhana untuk memulai adalah dengan caching otomatis:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    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 breakpoint cache 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 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 aktif 5 menit. Cache disegarkan tanpa biaya tambahan setiap kali konten yang di-cache digunakan.



Harga

Caching prompt memperkenalkan struktur harga baru. Tabel di bawah ini 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 breakpoint cache ke blok terakhir yang dapat di-cache.

client = anthropic.Anthropic()

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

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 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 breakpoint cache eksplisit. Ketika 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-4-8",
  "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 breakpoint cache otomatis, sistem secara diam-diam berjalan mundur untuk menemukan blok terdekat yang memenuhi syarat. Jika tidak ada yang ditemukan, caching dilewati.



Breakpoint cache 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 detail atas apa 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 level dibangun di atas level sebelumnya.



Cara kerja pemeriksaan prefiks otomatis

Anda dapat menggunakan hanya satu breakpoint cache 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 blok dengan cache_control menulis tepat satu entri cache: hash dari prefiks yang berakhir di blok tersebut. Sistem tidak menulis entri untuk posisi sebelumnya mana pun. 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 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 menyertakan 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 dari itu. Tidak ada cache hit. Anda membayar untuk 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, jadi 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 breakpoint cache 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 breakpoint cache

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

• Penulisan cache: Ketika konten baru ditulis ke cache (25% lebih mahal 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 sebenarnya di-cache dan dibaca. Breakpoint hanya 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 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 (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 Google Cloud)

Ketersediaan model bervariasi berdasarkan platform, begitu juga minimum untuk model yang baru dirilis: pada Amazon Bedrock, panjang prompt minimum yang dapat di-cache untuk Claude Fable 5 dan Claude Mythos 5 adalah 1.024 token.

Prompt yang lebih pendek tidak dapat di-cache, bahkan jika ditandai dengan cache_control. Permintaan apa pun untuk meng-cache kurang dari jumlah token ini akan diproses tanpa caching, dan tidak ada error yang dikembalikan. Untuk memverifikasi apakah 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 bermanfaat. Pembacaan cache jauh lebih murah 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 aktif 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 dan 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 dan assistant

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

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

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

• 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 level membatalkan level tersebut dan semua level berikutnya.

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



Melacak performa cache

Pantau performa cache menggunakan field respons API ini, 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 breakpoint cache terakhir).

total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens



Caching dengan blok thinking

Ketika menggunakan pemikiran diperpanjang dengan caching prompt, blok thinking memiliki perilaku khusus:

Caching otomatis bersama konten lain: Meskipun blok thinking tidak dapat secara eksplisit ditandai 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 penggunaan Anda. Ini penting untuk perhitungan biaya dan penganggaran token.

Pola pembatalan cache:

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

Untuk informasi lebih detail, lihat dokumentasi pemikiran diperpanjang.



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. Per 5 Februari 2026, cache juga diisolasi per workspace dalam satu 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 performa caching prompt:

• Mulai dengan caching otomatis untuk percakapan multi-giliran. Caching otomatis menangani manajemen breakpoint secara otomatis.
• Gunakan breakpoint tingkat blok eksplisit ketika 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 performa terbaik.
• Gunakan breakpoint cache 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 kasus penggunaan yang berbeda

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 coding: Tingkatkan autocomplete dan Q&A codebase dengan menyimpan bagian yang relevan atau versi ringkasan dari codebase dalam prompt.
• Pemrosesan dokumen besar: Sertakan 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. Developer sering menyertakan satu atau dua contoh dalam prompt, tetapi dengan caching prompt Anda bisa mendapatkan performa yang lebih baik dengan menyertakan 20+ contoh beragam dari jawaban berkualitas tinggi.
• Penggunaan alat agentic: Tingkatkan performa 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.



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 aktif cache (5 menit secara default)
• Verifikasi bahwa tool_choice dan penggunaan gambar tetap konsisten antar panggilan
• Validasi bahwa Anda meng-cache setidaknya jumlah token minimum untuk model dan platform Anda (lihat Batasan cache)
• Konfirmasi 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 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.

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

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

Respons akan 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 panduan ini tentang caching prompt dan penggunaan alat.



Kapan menggunakan cache 1 jam

Jika Anda memiliki prompt yang digunakan pada irama teratur (yaitu, prompt sistem yang digunakan lebih sering dari setiap 5 menit), terus gunakan cache 5 menit, karena ini akan terus disegarkan 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 agentic 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 setelah 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 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).

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 adalah 3 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.



Pre-warming cache

Pre-warming cache 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

Tetapkan max_tokens: 0 dalam permintaan Anda. API membaca prompt Anda ke dalam model dan menulis cache di breakpoint cache_control mana pun, lalu segera kembali 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 dikunci ke placeholder dan permintaan lanjutan tidak akan mengenainya. Ini berarti menggunakan breakpoint cache eksplisit daripada 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()

# Fire this before users arrive to warm the shared system-prompt cache.
prewarm = client.messages.create(
    model="claude-opus-4-8",
    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-4-8",
  "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 ketika aplikasi Anda dimulai (atau pada interval terjadwal), lalu kirim permintaan pengguna nyata 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-4-8",
        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-4-8",
        max_tokens=1024,
        system=SYSTEM_PROMPT,
        messages=[{"role": "user", "content": user_message}],
    )


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

# Kemudian, saat pengguna mengirim pesan, prefiks prompt sistem sudah di-cache.
response = respond("How do I implement a binary search tree?")
print(response.content[0].text)

Perlu diingat bahwa TTL cache tetap berlaku. Untuk cache 5 menit default, kirim permintaan pre-warm baru setidaknya setiap 5 menit untuk menjaga cache tetap hangat. Untuk jeda yang lebih lama antar permintaan pengguna, gunakan durasi cache 1 jam sebagai gantinya.



Batasan

Permintaan dengan max_tokens: 0 akan 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:

• 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. 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, prompt caching cookbook menyediakan contoh terperinci dan praktik terbaik.

Cuplikan kode berikut menampilkan berbagai pola caching prompt. Contoh-contoh ini mendemonstrasikan cara mengimplementasikan caching dalam berbagai skenario, 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 aktif minimum 5 menit (standar) atau 1 jam (diperpanjang), setelah itu entri tersebut akan dihapus dengan segera, meskipun tidak seketika. Entri cache diisolasi antar organisasi dan, pada Claude API, Claude Platform di AWS, dan Microsoft Foundry, antar workspace dalam satu organisasi.

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



FAQ