Prompt caching

Prompt caching mengoptimalkan penggunaan API Anda dengan memungkinkan melanjutkan dari 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 prompt caching:

• Caching otomatis: Tambahkan satu bidang cache_control di tingkat atas permintaan Anda. Sistem secara otomatis menerapkan breakpoint cache ke blok yang dapat di-cache terakhir dan memindahkannya maju seiring percakapan berkembang. Terbaik untuk percakapan multi-putaran di mana riwayat pesan yang berkembang harus di-cache secara otomatis.
• Breakpoint cache eksplisit: Tempatkan cache_control langsung pada blok konten individual untuk kontrol yang lebih halus 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-7",
    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 yang dapat di-cache terakhir. Pada permintaan berikutnya dengan awalan yang sama, konten yang di-cache digunakan kembali secara otomatis.

Cara kerja prompt caching

Ketika Anda mengirim permintaan dengan prompt caching diaktifkan:

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

Ini sangat berguna untuk:

• Prompt dengan banyak contoh
• Jumlah besar konteks atau informasi latar belakang
• Tugas berulang dengan instruksi yang konsisten
• Percakapan multi-putaran yang panjang

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

Harga

Prompt caching memperkenalkan struktur harga baru. Tabel di bawah menunjukkan harga per juta token untuk setiap model yang didukung:

Model yang didukung

Prompt caching (baik otomatis maupun eksplisit) didukung pada semua model Claude aktif.

Caching otomatis

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

client = anthropic.Anthropic()

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

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

Breakpoint cache secara otomatis bergerak ke blok yang dapat di-cache terakhir di setiap permintaan, jadi 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 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 dan alat Anda secara independen, sementara caching otomatis menangani percakapan:

{
  "model": "claude-opus-4-7",
  "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 yang sama. Harga, ambang token minimum, persyaratan pengurutan konteks, dan jendela lookback 20-blok semuanya berlaku sama seperti dengan breakpoint eksplisit.

Kasus tepi

• Jika blok terakhir sudah memiliki cache_control eksplisit dengan TTL yang sama, caching otomatis adalah no-op.
• Jika blok terakhir memiliki cache_control eksplisit dengan TTL yang berbeda, API mengembalikan kesalahan 400.
• Jika 4 breakpoint tingkat blok eksplisit sudah ada, API mengembalikan kesalahan 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 yang memenuhi syarat terdekat. 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 yang lebih halus 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.

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

Cara kerja pemeriksaan awalan otomatis

Anda dapat menggunakan hanya satu breakpoint cache di akhir konten statis Anda, dan sistem akan secara otomatis menemukan awalan terpanjang yang telah ditulis permintaan sebelumnya ke cache. 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 awalan yang berakhir di blok itu. Sistem tidak menulis entri untuk posisi apa pun sebelumnya. Karena hash bersifat kumulatif, mencakup semuanya hingga dan termasuk breakpoint, mengubah blok apa pun di atau sebelum breakpoint menghasilkan hash berbeda pada permintaan berikutnya.

2. Pembacaan cache mencari mundur untuk entri yang ditulis permintaan sebelumnya. Pada setiap permintaan, sistem menghitung hash awalan di breakpoint Anda dan memeriksa entri cache yang cocok. Jika tidak ada, sistem berjalan mundur satu blok pada satu waktu, memeriksa apakah hash awalan di setiap posisi sebelumnya cocok dengan sesuatu yang sudah ada di cache. Sistem mencari penulisan sebelumnya, bukan konten 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 di jendela itu, pemeriksaan berhenti (atau dilanjutkan dari breakpoint eksplisit berikutnya, jika ada).

Contoh: Lookback dalam percakapan yang berkembang

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

• Putaran 1: 10 blok, breakpoint pada blok 10. Tidak ada entri cache sebelumnya. Sistem menulis entri di blok 10.
• Putaran 2: 15 blok, breakpoint pada blok 15. Blok 15 tidak memiliki entri, jadi sistem berjalan mundur ke blok 10 dan menemukan entri putaran-1. Cache hit di blok 10; sistem hanya memproses blok 11 hingga 15 segar dan menulis entri baru di blok 15.
• Putaran 3: 35 blok, breakpoint pada blok 35. Sistem memeriksa 20 posisi (blok 35 hingga 16) dan tidak menemukan apa pun. Entri putaran-2 di blok 15 adalah 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 putaran-2.

Kesalahan umum: Breakpoint pada konten yang berubah setiap permintaan

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

• Permintaan 1: Penulisan cache di blok 6. Hash mencakup stempel waktu.
• Permintaan 2: Stempel waktu berbeda, jadi hash awalan di blok 6 berbeda. Lookback berjalan melalui blok 5, 4, 3, 2, dan 1, tetapi sistem tidak pernah menulis entri di posisi apa pun. Tidak ada cache hit. Anda membayar penulisan cache segar pada setiap permintaan dan tidak pernah mendapatkan pembacaan.

Lookback tidak menemukan konten stabil di belakang breakpoint Anda dan meng-cachenya. Lookback menemukan entri yang telah ditulis 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 awalan yang di-cache. Caching otomatis mengenai jebakan yang sama: menempatkan breakpoint pada blok yang dapat di-cache terakhir, yang dalam struktur ini adalah yang berubah setiap permintaan, jadi gunakan breakpoint eksplisit pada blok 5 sebagai gantinya.

Kesimpulan kunci: Tempatkan cache_control pada blok terakhir yang awalannya identik di seluruh permintaan yang ingin Anda bagikan cache. Dalam percakapan yang berkembang, blok terakhir berfungsi selama setiap putaran menambahkan lebih sedikit dari 20 blok: konten sebelumnya tidak pernah berubah, jadi lookback permintaan berikutnya menemukan penulisan sebelumnya. Untuk prompt dengan akhiran yang bervariasi (stempel waktu, konteks per-permintaan, pesan masuk), tempatkan breakpoint di akhir awalan statis, bukan pada blok yang bervariasi.

Kapan menggunakan beberapa breakpoint

Anda dapat menentukan 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 atau lebih blok melampaui 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 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 masih 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 caching dan pertimbangan

Batasan caching

Panjang prompt yang dapat di-cache minimum adalah:

• 4096 token untuk Claude Mythos Preview, Claude Opus 4.7, Claude Opus 4.6, dan Claude Opus 4.5
• 2048 token untuk Claude Sonnet 4.6
• 1024 token untuk Claude Sonnet 4.5, Claude Opus 4.1, Claude Opus 4, Claude Sonnet 4, dan Claude Sonnet 3.7 (deprecated)
• 4096 token untuk Claude Haiku 4.5
• 2048 token untuk Claude Haiku 3.5 (deprecated) dan Claude Haiku 3

Prompt yang lebih pendek tidak dapat di-cache, bahkan jika ditandai dengan cache_control. Permintaan apa pun untuk meng-cache lebih sedikit dari jumlah token ini akan diproses tanpa caching, dan tidak ada kesalahan yang dikembalikan. Untuk memverifikasi apakah prompt di-cache, periksa bidang penggunaan respons: jika baik cache_creation_input_tokens dan cache_read_input_tokens adalah 0, prompt tidak di-cache (kemungkinan karena tidak memenuhi persyaratan panjang minimum).

Jika prompt Anda sedikit di bawah minimum untuk model yang Anda gunakan, memperluas konten yang di-cache untuk mencapai ambang batas sering kali bermanfaat. Token pembacaan cache biaya jauh lebih sedikit 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 jenis cache yang didukung, yang secara default memiliki masa pakai 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 putaran pengguna dan asisten
• Gambar & Dokumen: Blok konten dalam array messages.content, dalam putaran pengguna
• Penggunaan alat dan hasil alat: Blok konten dalam array messages.content, dalam putaran pengguna dan asisten

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 pemikiran tidak dapat di-cache langsung dengan cache_control. Namun, blok pemikiran DAPAT di-cache bersama konten lain ketika muncul dalam putaran asisten sebelumnya. Ketika di-cache dengan cara ini, mereka MENGHITUNG sebagai token input ketika dibaca dari cache.

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

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

• Blok teks kosong tidak dapat di-cache.

Apa yang membatalkan cache

Modifikasi 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 itu dan semua level berikutnya.

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

Melacak kinerja cache

Pantau kinerja cache menggunakan bidang respons API ini, dalam usage dalam respons (atau acara message_start jika 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 thinking blocks

Saat menggunakan extended thinking dengan prompt caching, thinking blocks memiliki perilaku khusus:

Automatic caching bersama konten lainnya: Meskipun thinking blocks tidak dapat secara eksplisit ditandai dengan cache_control, mereka di-cache sebagai bagian dari konten permintaan ketika Anda membuat panggilan API berikutnya dengan hasil tool. Ini biasanya terjadi selama penggunaan tool ketika Anda mengirimkan thinking blocks kembali untuk melanjutkan percakapan.

Input token counting: Ketika thinking blocks dibaca dari cache, mereka dihitung sebagai input tokens dalam metrik penggunaan Anda. Ini penting untuk perhitungan biaya dan perencanaan token budget.

Cache invalidation patterns:

• Cache tetap valid ketika hanya hasil tool yang disediakan sebagai pesan pengguna
• Cache menjadi tidak valid ketika konten pengguna non-tool-result ditambahkan, menyebabkan semua thinking blocks sebelumnya dihapus
• Perilaku caching ini terjadi bahkan tanpa penanda cache_control eksplisit

Untuk detail lebih lanjut tentang cache invalidation, lihat What invalidates the cache.

Contoh dengan tool use:

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]
# Non-tool-result user block causes all thinking blocks to be ignored
# This request is processed as if thinking blocks were never present

Ketika blok pengguna non-tool-result disertakan, itu menunjuk loop asisten baru dan semua thinking blocks sebelumnya dihapus dari konteks.

Untuk informasi lebih detail, lihat dokumentasi extended thinking.

Cache storage and sharing

• Organization Isolation: Cache diisolasi antara organisasi. Organisasi yang berbeda tidak pernah berbagi cache, bahkan jika mereka menggunakan prompt yang identik.

• Exact Matching: Cache hits memerlukan prompt segments yang 100% identik, termasuk semua teks dan gambar hingga dan termasuk blok yang ditandai dengan cache control.

• Output Token Generation: Prompt caching tidak memiliki efek pada pembuatan output token. Respons yang Anda terima akan identik dengan apa yang akan Anda dapatkan jika prompt caching tidak digunakan.

Best practices untuk caching yang efektif

Untuk mengoptimalkan kinerja prompt caching:

• Mulai dengan automatic caching untuk percakapan multi-turn. Ini menangani manajemen breakpoint secara otomatis.
• Gunakan explicit block-level breakpoints ketika Anda perlu cache bagian berbeda dengan frekuensi perubahan yang berbeda.
• Cache konten stabil dan dapat digunakan kembali seperti instruksi sistem, informasi latar belakang, konteks besar, atau definisi tool yang sering digunakan.
• Tempatkan konten cache di awal prompt untuk kinerja terbaik.
• Gunakan cache breakpoints secara strategis untuk memisahkan bagian prefix yang berbeda dan dapat di-cache.
• Tempatkan breakpoint pada blok terakhir yang tetap identik di seluruh permintaan. Untuk prompt dengan prefix statis dan suffix yang bervariasi (timestamps, konteks per-permintaan, pesan masuk), itu adalah akhir dari prefix, bukan blok yang bervariasi.
• Secara teratur analisis cache hit rates dan sesuaikan strategi Anda sesuai kebutuhan.

Optimizing untuk use cases yang berbeda

Sesuaikan strategi prompt caching Anda dengan skenario Anda:

• Conversational agents: Kurangi biaya dan latency untuk percakapan yang diperpanjang, terutama yang memiliki instruksi panjang atau dokumen yang diunggah.
• Coding assistants: Tingkatkan autocomplete dan codebase Q&A dengan menjaga bagian relevan atau versi ringkasan codebase dalam prompt.
• Large document processing: Gabungkan materi bentuk panjang lengkap termasuk gambar dalam prompt Anda tanpa meningkatkan latency respons.
• Detailed instruction sets: Bagikan daftar instruksi, prosedur, dan contoh yang luas untuk menyempurnakan respons Claude. Developer sering menyertakan satu atau dua contoh dalam prompt, tetapi dengan prompt caching Anda dapat mendapatkan kinerja yang lebih baik dengan menyertakan 20+ contoh beragam jawaban berkualitas tinggi.
• Agentic tool use: Tingkatkan kinerja untuk skenario yang melibatkan beberapa panggilan tool dan perubahan kode iteratif, di mana setiap langkah biasanya memerlukan panggilan API baru.
• Talk to books, papers, documentation, podcast transcripts, dan konten longform lainnya: Hidupkan basis pengetahuan apa pun dengan menyematkan seluruh dokumen ke dalam prompt, dan biarkan pengguna mengajukan pertanyaan kepadanya.

Troubleshooting common issues

Jika mengalami perilaku yang tidak terduga:

• Pastikan bagian cache identik di seluruh panggilan. Untuk breakpoints eksplisit, verifikasi bahwa penanda cache_control berada di lokasi yang sama
• Periksa bahwa panggilan dilakukan dalam cache lifetime (5 menit secara default)
• Verifikasi bahwa tool_choice dan penggunaan gambar tetap konsisten antara panggilan
• Validasi bahwa Anda melakukan cache setidaknya jumlah minimum token untuk model yang Anda gunakan (lihat Cache limitations). Kegagalan caching berbasis panjang bersifat senyap: permintaan berhasil tetapi baik cache_creation_input_tokens dan cache_read_input_tokens akan menjadi 0
• Konfirmasi breakpoint Anda berada pada blok yang tetap identik di seluruh permintaan. Cache writes terjadi hanya pada breakpoint, dan jika blok itu berubah (timestamps, konteks per-permintaan, pesan masuk), hash prefix tidak pernah cocok. Lookback tidak menemukan konten stabil di belakang breakpoint; itu hanya menemukan entri yang permintaan sebelumnya tulis di breakpoint mereka sendiri
• Verifikasi bahwa kunci dalam blok konten tool_use Anda memiliki pengurutan stabil karena beberapa bahasa (misalnya, Swift, Go) mengacakkan urutan kunci selama konversi JSON, merusak cache

1-hour cache duration

Jika Anda menemukan bahwa 5 menit terlalu pendek, Anthropic juga menawarkan durasi cache 1 jam dengan biaya tambahan.

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

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

Respons akan 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": 456,
      "ephemeral_1h_input_tokens": 100
    }
  }
}

Perhatikan bahwa field cache_creation_input_tokens saat ini sama dengan jumlah nilai dalam objek cache_creation.

When to use the 1-hour cache

Jika Anda memiliki prompt yang digunakan dengan ritme teratur (yaitu, prompt sistem yang digunakan lebih sering daripada setiap 5 menit), lanjutkan menggunakan 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 daripada 5 menit, tetapi lebih sering daripada setiap jam. Misalnya, ketika side-agent agentic akan memakan waktu lebih lama dari 5 menit, atau ketika menyimpan percakapan chat panjang dengan pengguna dan Anda umumnya mengharapkan bahwa pengguna mungkin tidak merespons dalam 5 menit berikutnya.
• Ketika latency penting dan prompt follow-up Anda mungkin dikirim di luar 5 menit.
• Ketika Anda ingin meningkatkan utilisasi rate limit Anda, karena cache hits tidak dikurangkan dari rate limit Anda.

Mixing different TTLs

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

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

1. Position A: Jumlah token pada cache hit tertinggi (atau 0 jika tidak ada hits).
2. Position B: Jumlah token pada blok cache_control 1 jam tertinggi setelah A (atau sama dengan A jika tidak ada).
3. Position C: Jumlah token pada blok cache_control terakhir.

Anda akan dikenakan biaya untuk:

1. Cache read tokens untuk A.
2. 1-hour cache write tokens untuk (B - A).
3. 5-minute cache write tokens untuk (C - B).

Berikut adalah 3 contoh. Ini menggambarkan input tokens dari 3 permintaan, masing-masing memiliki cache hits dan cache misses yang berbeda. Masing-masing memiliki penagihan yang dihitung berbeda, ditunjukkan dalam kotak berwarna, sebagai hasilnya.

Contoh prompt caching

Untuk membantu Anda memulai dengan prompt caching, prompt caching cookbook menyediakan contoh terperinci dan praktik terbaik.

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

Retensi data

Prompt caching (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 kriptografi dari konten yang di-cache disimpan hanya dalam memori dan tidak disimpan saat istirahat. Entri cache memiliki masa hidup minimum 5 menit (standar) atau 60 menit (diperpanjang), setelah itu dihapus dengan cepat, meskipun tidak segera. Entri cache terisolasi antar organisasi.

Untuk kelayakan ZDR di semua fitur, lihat API and data retention.

FAQ