Prompt caching adalah fitur yang kuat yang mengoptimalkan penggunaan API Anda dengan memungkinkan melanjutkan dari prefiks tertentu dalam prompt Anda. Pendekatan ini secara signifikan mengurangi waktu pemrosesan dan biaya untuk tugas berulang atau prompt dengan elemen yang konsisten.

Berikut adalah contoh cara mengimplementasikan prompt caching dengan Messages API menggunakan blok cache_control:

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
      },
      {
        "type": "text",
        "text": "<the entire contents of Pride and Prejudice>",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Analyze the major themes in Pride and Prejudice."
      }
    ]
  }'

# Call the model again with the same inputs up to the cache checkpoint
curl https://api.anthropic.com/v1/messages # rest of input
JSON
{"cache_creation_input_tokens":188086,"cache_read_input_tokens":0,"input_tokens":21,"output_tokens":393}
{"cache_creation_input_tokens":0,"cache_read_input_tokens":188086,"input_tokens":21,"output_tokens":393}

Dalam contoh ini, seluruh teks “Pride and Prejudice” di-cache menggunakan parameter cache_control. Ini memungkinkan penggunaan kembali teks besar ini di beberapa panggilan API tanpa memproses ulang setiap kali. Mengubah hanya pesan pengguna memungkinkan Anda mengajukan berbagai pertanyaan tentang buku sambil memanfaatkan konten yang di-cache, menghasilkan respons yang lebih cepat dan efisiensi yang lebih baik.


Cara kerja prompt caching

Ketika Anda mengirim permintaan dengan prompt caching diaktifkan:

  1. Sistem memeriksa apakah prefiks prompt, hingga titik 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 penuh dan meng-cache prefiks 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-turn yang panjang

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

Jika Anda merasa 5 menit terlalu singkat, Anthropic juga menawarkan durasi cache 1 jam.

Untuk informasi lebih lanjut, lihat Durasi cache 1 jam.

Prompt caching meng-cache prefiks penuh

Prompt caching mereferensikan seluruh prompt - tools, system, dan messages (dalam urutan tersebut) hingga dan termasuk blok yang ditandai dengan cache_control.


Harga

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

ModelBase Input Tokens5m Cache Writes1h Cache WritesCache Hits & RefreshesOutput Tokens
Claude Opus 4.1$15 / MTok$18.75 / MTok$30 / MTok$1.50 / MTok$75 / MTok
Claude Opus 4$15 / MTok$18.75 / MTok$30 / MTok$1.50 / MTok$75 / MTok
Claude Sonnet 4$3 / MTok$3.75 / MTok$6 / MTok$0.30 / MTok$15 / MTok
Claude Sonnet 3.7$3 / MTok$3.75 / MTok$6 / MTok$0.30 / MTok$15 / MTok
Claude Sonnet 3.5 (deprecated)$3 / MTok$3.75 / MTok$6 / MTok$0.30 / MTok$15 / MTok
Claude Haiku 3.5$0.80 / MTok$1 / MTok$1.6 / MTok$0.08 / MTok$4 / MTok
Claude Opus 3 (deprecated)$15 / MTok$18.75 / MTok$30 / MTok$1.50 / MTok$75 / MTok
Claude Haiku 3$0.25 / MTok$0.30 / MTok$0.50 / MTok$0.03 / MTok$1.25 / MTok

Tabel di atas mencerminkan pengali harga berikut untuk prompt caching:

  • Token tulis cache 5 menit adalah 1,25 kali harga token input dasar
  • Token tulis cache 1 jam adalah 2 kali harga token input dasar
  • Token baca cache adalah 0,1 kali harga token input dasar

Cara mengimplementasikan prompt caching

Model yang didukung

Prompt caching saat ini didukung pada:

  • Claude Opus 4.1
  • Claude Opus 4
  • Claude Sonnet 4
  • Claude Sonnet 3.7
  • Claude Sonnet 3.5 (deprecated)
  • Claude Haiku 3.5
  • Claude Haiku 3
  • Claude Opus 3 (deprecated)

Menyusun prompt Anda

Tempatkan konten statis (definisi tool, 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, kemudian messages. Urutan ini membentuk hierarki di mana setiap level dibangun berdasarkan 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 yang cocok terpanjang. Begini cara kerjanya:

  • Ketika Anda menambahkan breakpoint cache_control, sistem secara otomatis memeriksa cache hit di semua batas blok konten sebelumnya (hingga sekitar 20 blok sebelum breakpoint eksplisit Anda)
  • Jika ada dari posisi sebelumnya ini cocok dengan konten yang di-cache dari permintaan sebelumnya, sistem menggunakan prefiks yang cocok terpanjang
  • Ini berarti Anda tidak perlu beberapa breakpoint hanya untuk mengaktifkan caching - satu di akhir sudah cukup

Kapan menggunakan beberapa breakpoint

Anda dapat mendefinisikan hingga 4 breakpoint cache jika Anda ingin:

  • Meng-cache bagian berbeda yang berubah pada frekuensi berbeda (misalnya, tools jarang berubah, tetapi konteks diperbarui setiap hari)
  • Memiliki kontrol lebih atas apa yang di-cache
  • Memastikan caching untuk konten lebih dari 20 blok sebelum breakpoint terakhir Anda

Keterbatasan penting: Pemeriksaan prefiks otomatis hanya melihat kembali sekitar 20 blok konten dari setiap breakpoint eksplisit. Jika prompt Anda memiliki lebih dari 20 blok konten sebelum breakpoint cache Anda, konten yang lebih awal dari itu tidak akan diperiksa untuk cache hit kecuali Anda menambahkan breakpoint tambahan.

Keterbatasan cache

Panjang prompt minimum yang dapat di-cache adalah:

  • 1024 token untuk Claude Opus 4, Claude Sonnet 4, Claude Sonnet 3.7, Claude Sonnet 3.5 (deprecated) dan Claude Opus 3 (deprecated)
  • 2048 token untuk Claude Haiku 3.5 dan Claude Haiku 3

Prompt yang lebih pendek tidak dapat di-cache, bahkan jika ditandai dengan cache_control. Setiap permintaan untuk meng-cache lebih sedikit dari jumlah token ini akan diproses tanpa caching. Untuk melihat apakah prompt di-cache, lihat fields penggunaan respons.

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 hidup 5 menit.

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 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 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 hanya memberi Anda kontrol atas bagian mana yang dapat di-cache secara independen.

Apa yang dapat di-cache

Sebagian besar blok dalam permintaan dapat ditandai untuk caching dengan cache_control. Ini termasuk:

  • Tools: Definisi tool dalam array tools
  • Pesan sistem: Blok konten dalam array system
  • Pesan teks: Blok konten dalam array messages.content, untuk turn pengguna dan asisten
  • Gambar & Dokumen: Blok konten dalam array messages.content, dalam turn pengguna
  • Penggunaan tool dan hasil tool: Blok konten dalam array messages.content, dalam turn pengguna dan asisten

Setiap elemen ini dapat ditandai dengan cache_control untuk mengaktifkan caching untuk bagian permintaan tersebut.

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 turn asisten sebelumnya. Ketika di-cache dengan cara ini, mereka DIHITUNG sebagai token input ketika dibaca dari cache.

  • Sub-blok konten (seperti citations) sendiri tidak dapat di-cache secara langsung. Sebaliknya, 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 prompt caching 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: toolssystemmessages. 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.

Apa yang berubahCache toolsCache systemCache messagesDampak
Definisi toolMemodifikasi definisi tool (nama, deskripsi, parameter) membatalkan seluruh cache
Toggle pencarian webMengaktifkan/menonaktifkan pencarian web memodifikasi prompt sistem
Toggle citationsMengaktifkan/menonaktifkan citations memodifikasi prompt sistem
Pilihan toolPerubahan pada parameter tool_choice hanya mempengaruhi blok pesan
GambarMenambah/menghapus gambar di mana pun dalam prompt mempengaruhi blok pesan
Parameter thinkingPerubahan pada pengaturan extended thinking (aktif/nonaktif, anggaran) mempengaruhi blok pesan
Hasil non-tool yang diteruskan ke permintaan extended thinkingKetika hasil non-tool diteruskan dalam permintaan saat extended thinking diaktifkan, semua blok thinking yang sebelumnya di-cache dihapus dari konteks, dan pesan apa pun dalam konteks yang mengikuti blok thinking tersebut dihapus dari cache. Untuk detail lebih lanjut, lihat Caching dengan blok thinking.

Melacak performa cache

Pantau performa cache menggunakan field respons API ini, dalam usage di respons (atau event 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.

Praktik terbaik untuk caching yang efektif

Untuk mengoptimalkan performa prompt caching:

  • Cache konten yang stabil dan dapat digunakan kembali seperti instruksi sistem, informasi latar belakang, konteks besar, atau definisi tool 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 berbeda.
  • Analisis tingkat cache hit secara teratur dan sesuaikan strategi Anda sesuai kebutuhan.

Mengoptimalkan untuk kasus penggunaan berbeda

Sesuaikan strategi prompt caching 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 menjaga bagian yang relevan atau versi ringkasan codebase dalam prompt.
  • Pemrosesan dokumen besar: Sertakan materi bentuk panjang lengkap termasuk gambar dalam prompt Anda tanpa meningkatkan latensi respons.
  • Set instruksi terperinci: Bagikan daftar instruksi, prosedur, dan contoh yang ekstensif untuk menyetel respons Claude. Developer sering menyertakan satu atau dua contoh dalam prompt, tetapi dengan prompt caching Anda bisa mendapatkan performa yang lebih baik dengan menyertakan 20+ contoh beragam jawaban berkualitas tinggi.
  • Penggunaan tool agentic: Tingkatkan performa untuk skenario yang melibatkan beberapa panggilan tool dan perubahan kode iteratif, di mana setiap langkah biasanya memerlukan panggilan API baru.
  • Berbicara dengan buku, makalah, dokumentasi, transkrip podcast, dan konten bentuk panjang lainnya: Hidupkan basis pengetahuan apa pun dengan menyematkan seluruh dokumen ke dalam prompt, dan biarkan pengguna mengajukan pertanyaan.

Mengatasi masalah umum

Jika mengalami perilaku yang tidak terduga:

  • Pastikan bagian yang di-cache identik dan ditandai dengan cache_control di lokasi yang sama di seluruh panggilan
  • Periksa bahwa panggilan dibuat dalam masa hidup 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
  • Sistem secara otomatis memeriksa cache hit di batas blok konten sebelumnya (hingga ~20 blok sebelum breakpoint Anda). Untuk prompt dengan lebih dari 20 blok konten, Anda mungkin perlu parameter cache_control tambahan lebih awal dalam prompt untuk memastikan semua konten dapat di-cache

Perubahan pada tool_choice atau keberadaan/ketidakberadaan gambar di mana pun dalam prompt akan membatalkan cache, memerlukan entri cache baru untuk dibuat. Untuk detail lebih lanjut tentang pembatalan cache, lihat Apa yang membatalkan cache.

Caching dengan blok thinking

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

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

Penghitungan token input: Ketika blok thinking dibaca dari cache, mereka 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 tool yang disediakan sebagai pesan pengguna
  • Cache dibatalkan ketika konten pengguna non-tool-result ditambahkan, menyebabkan semua blok thinking sebelumnya dihapus
  • 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 tool:

Permintaan 1: Pengguna: "Bagaimana cuaca di Paris?"
Respons: [thinking_block_1] + [blok tool_use 1]

Permintaan 2: 
Pengguna: ["Bagaimana cuaca di Paris?"], 
Asisten: [thinking_block_1] + [blok tool_use 1], 
Pengguna: [tool_result_1, cache=True]
Respons: [thinking_block_2] + [blok teks 2]
# Permintaan 2 meng-cache konten permintaannya (bukan respons)
# Cache mencakup: pesan pengguna, thinking_block_1, blok tool_use 1, dan tool_result_1

Permintaan 3:
Pengguna: ["Bagaimana cuaca di Paris?"], 
Asisten: [thinking_block_1] + [blok tool_use 1], 
Pengguna: [tool_result_1, cache=True], 
Asisten: [thinking_block_2] + [blok teks 2], 
Pengguna: [Respons teks, cache=True]
# Blok pengguna non-tool-result menyebabkan semua blok thinking diabaikan
# Permintaan ini diproses seolah-olah blok thinking tidak pernah ada

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

Untuk informasi lebih detail, lihat dokumentasi extended thinking.


Penyimpanan dan berbagi cache

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

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

  • Generasi Token Output: Prompt caching tidak berpengaruh pada generasi token output. Respons yang Anda terima akan identik dengan yang akan Anda dapatkan jika prompt caching tidak digunakan.


Durasi cache 1 jam

Jika Anda merasa 5 menit terlalu singkat, Anthropic juga menawarkan durasi cache 1 jam.

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

"cache_control": {
    "type": "ephemeral",
    "ttl": "5m" | "1h"
}

Respons akan mencakup informasi cache terperinci seperti berikut:

{
    "usage": {
        "input_tokens": ...,
        "cache_read_input_tokens": ...,
        "cache_creation_input_tokens": ...,
        "output_tokens": ...,
        
        "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.

Kapan menggunakan cache 1 jam

Jika Anda memiliki prompt yang digunakan pada irama reguler (yaitu, prompt sistem yang digunakan lebih sering daripada setiap 5 menit), lanjutkan menggunakan 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 agen samping agentic akan memakan waktu lebih dari 5 menit, atau ketika menyimpan percakapan chat panjang dengan pengguna dan Anda umumnya mengharapkan pengguna tersebut mungkin tidak merespons dalam 5 menit ke depan.
  • Ketika latensi penting dan prompt lanjutan Anda mungkin dikirim lebih dari 5 menit.
  • Ketika Anda ingin meningkatkan pemanfaatan batas tarif Anda, karena cache hit tidak dikurangkan dari batas tarif Anda.

Cache 5 menit dan 1 jam berperilaku sama dalam hal latensi. Anda umumnya akan melihat peningkatan time-to-first-token untuk dokumen panjang.

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 apa pun).

Ketika mencampur TTL, kami 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.

Jika B dan/atau C lebih besar dari A, mereka tentu akan menjadi cache miss, karena A adalah cache hit tertinggi.

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 adalah 3 contoh. Ini menggambarkan token input dari 3 permintaan, masing-masing memiliki cache hit dan cache miss yang berbeda. Masing-masing memiliki perhitungan harga yang berbeda, ditunjukkan dalam kotak berwarna, sebagai hasilnya.


Contoh prompt caching

Untuk membantu Anda memulai dengan prompt caching, kami telah menyiapkan cookbook prompt caching dengan contoh terperinci dan praktik terbaik.

Di bawah ini, kami telah menyertakan beberapa cuplikan kode yang menampilkan berbagai pola prompt caching. Contoh-contoh ini mendemonstrasikan cara mengimplementasikan caching dalam skenario yang berbeda, membantu Anda memahami aplikasi praktis dari fitur ini:


FAQ