Prompt caching

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:

Sistem memeriksa apakah prefiks prompt, hingga titik breakpoint cache yang ditentukan, sudah di-cache dari kueri terbaru.
Jika ditemukan, sistem menggunakan versi yang di-cache, mengurangi waktu pemrosesan dan biaya.
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:

Model	Base Input Tokens	5m Cache Writes	1h Cache Writes	Cache Hits & Refreshes	Output 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: 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.

Apa yang berubah	Cache tools	Cache system	Cache messages	Dampak
Definisi tool	✘	✘	✘	Memodifikasi definisi tool (nama, deskripsi, parameter) membatalkan seluruh cache
Toggle pencarian web	✓	✘	✘	Mengaktifkan/menonaktifkan pencarian web memodifikasi prompt sistem
Toggle citations	✓	✘	✘	Mengaktifkan/menonaktifkan citations memodifikasi prompt sistem
Pilihan tool	✓	✓	✘	Perubahan pada parameter `tool_choice` hanya mempengaruhi blok pesan
Gambar	✓	✓	✘	Menambah/menghapus gambar di mana pun dalam prompt mempengaruhi blok pesan
Parameter thinking	✓	✓	✘	Perubahan pada pengaturan extended thinking (aktif/nonaktif, anggaran) mempengaruhi blok pesan
Hasil non-tool yang diteruskan ke permintaan extended thinking	✓	✓	✘	Ketika 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:

Posisi A: Jumlah token pada cache hit tertinggi (atau 0 jika tidak ada hit).
Posisi B: Jumlah token pada blok cache_control 1 jam tertinggi setelah A (atau sama dengan A jika tidak ada).
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:

Token baca cache untuk A.
Token tulis cache 1 jam untuk (B - A).
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:

Contoh caching konteks besar

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "system": [
        {
            "type": "text",
            "text": "You are an AI assistant tasked with analyzing legal documents."
        },
        {
            "type": "text",
            "text": "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "What are the key terms and conditions in this agreement?"
        }
    ]
}'

Contoh ini mendemonstrasikan penggunaan prompt caching dasar, meng-cache teks lengkap perjanjian hukum sebagai prefiks sambil menjaga instruksi pengguna tidak di-cache.

Untuk permintaan pertama:

input_tokens: Jumlah token dalam pesan pengguna saja
cache_creation_input_tokens: Jumlah token dalam seluruh pesan sistem, termasuk dokumen hukum
cache_read_input_tokens: 0 (tidak ada cache hit pada permintaan pertama)

Untuk permintaan berikutnya dalam masa hidup cache:

input_tokens: Jumlah token dalam pesan pengguna saja
cache_creation_input_tokens: 0 (tidak ada pembuatan cache baru)
cache_read_input_tokens: Jumlah token dalam seluruh pesan sistem yang di-cache

Caching definisi tool

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "The unit of temperature, either celsius or fahrenheit"
                    }
                },
                "required": ["location"]
            }
        },
        # many more tools
        {
            "name": "get_time",
            "description": "Get the current time in a given time zone",
            "input_schema": {
                "type": "object",
                "properties": {
                    "timezone": {
                        "type": "string",
                        "description": "The IANA time zone name, e.g. America/Los_Angeles"
                    }
                },
                "required": ["timezone"]
            },
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "What is the weather and time in New York?"
        }
    ]
}'

Dalam contoh ini, kami mendemonstrasikan caching definisi tool.

Parameter cache_control ditempatkan pada tool terakhir (get_time) untuk menandai semua tool sebagai bagian dari prefiks statis.

Ini berarti bahwa semua definisi tool, termasuk get_weather dan tool lain yang didefinisikan sebelum get_time, akan di-cache sebagai prefiks tunggal.

Pendekatan ini berguna ketika Anda memiliki set tool yang konsisten yang ingin Anda gunakan kembali di beberapa permintaan tanpa memproses ulang setiap kali.

Untuk permintaan pertama:

input_tokens: Jumlah token dalam pesan pengguna
cache_creation_input_tokens: Jumlah token dalam semua definisi tool dan prompt sistem
cache_read_input_tokens: 0 (tidak ada cache hit pada permintaan pertama)

Untuk permintaan berikutnya dalam masa hidup cache:

input_tokens: Jumlah token dalam pesan pengguna
cache_creation_input_tokens: 0 (tidak ada pembuatan cache baru)
cache_read_input_tokens: Jumlah token dalam semua definisi tool dan prompt sistem yang di-cache

Melanjutkan percakapan multi-turn

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "system": [
        {
            "type": "text",
            "text": "...long system prompt",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Hello, can you tell me more about the solar system?",
                }
            ]
        },
        {
            "role": "assistant",
            "content": "Certainly! The solar system is the collection of celestial bodies that orbit our Sun. It consists of eight planets, numerous moons, asteroids, comets, and other objects. The planets, in order from closest to farthest from the Sun, are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune. Each planet has its own unique characteristics and features. Is there a specific aspect of the solar system you would like to know more about?"
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Good to know."
                },
                {
                    "type": "text",
                    "text": "Tell me more about Mars.",
                    "cache_control": {"type": "ephemeral"}
                }
            ]
        }
    ]
}'

Dalam contoh ini, kami mendemonstrasikan cara menggunakan prompt caching dalam percakapan multi-turn.

Selama setiap turn, kami menandai blok terakhir dari pesan terakhir dengan cache_control sehingga percakapan dapat di-cache secara bertahap. Sistem akan secara otomatis mencari dan menggunakan prefiks yang di-cache sebelumnya terpanjang untuk pesan lanjutan. Artinya, blok yang sebelumnya ditandai dengan blok cache_control kemudian tidak ditandai dengan ini, tetapi mereka masih akan dianggap sebagai cache hit (dan juga penyegaran cache!) jika mereka di-hit dalam 5 menit.

Selain itu, perhatikan bahwa parameter cache_control ditempatkan pada pesan sistem. Ini untuk memastikan bahwa jika ini dikeluarkan dari cache (setelah tidak digunakan selama lebih dari 5 menit), itu akan ditambahkan kembali ke cache pada permintaan berikutnya.

Pendekatan ini berguna untuk mempertahankan konteks dalam percakapan yang sedang berlangsung tanpa berulang kali memproses informasi yang sama.

Ketika ini diatur dengan benar, Anda harus melihat yang berikut dalam respons penggunaan setiap permintaan:

input_tokens: Jumlah token dalam pesan pengguna baru (akan minimal)
cache_creation_input_tokens: Jumlah token dalam turn asisten dan pengguna baru
cache_read_input_tokens: Jumlah token dalam percakapan hingga turn sebelumnya

Menggabungkan semuanya: Beberapa breakpoint cache

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

Contoh komprehensif ini mendemonstrasikan cara menggunakan semua 4 breakpoint cache yang tersedia untuk mengoptimalkan bagian berbeda dari prompt Anda:

Cache tools (breakpoint cache 1): Parameter cache_control pada definisi tool terakhir meng-cache semua definisi tool.
Cache instruksi yang dapat digunakan kembali (breakpoint cache 2): Instruksi statis dalam prompt sistem di-cache secara terpisah. Instruksi ini jarang berubah antar permintaan.
Cache konteks RAG (breakpoint cache 3): Dokumen basis pengetahuan di-cache secara independen, memungkinkan Anda memperbarui dokumen RAG tanpa membatalkan cache tools atau instruksi.
Cache riwayat percakapan (breakpoint cache 4): Respons asisten ditandai dengan cache_control untuk mengaktifkan caching bertahap percakapan saat berlangsung.

Pendekatan ini memberikan fleksibilitas maksimum:

Jika Anda hanya memperbarui pesan pengguna terakhir, keempat segmen cache digunakan kembali
Jika Anda memperbarui dokumen RAG tetapi menjaga tools dan instruksi yang sama, dua segmen cache pertama digunakan kembali
Jika Anda mengubah percakapan tetapi menjaga tools, instruksi, dan dokumen yang sama, tiga segmen pertama digunakan kembali
Setiap breakpoint cache dapat dibatalkan secara independen berdasarkan apa yang berubah dalam aplikasi Anda

Untuk permintaan pertama:

input_tokens: Token dalam pesan pengguna terakhir
cache_creation_input_tokens: Token dalam semua segmen yang di-cache (tools + instruksi + dokumen RAG + riwayat percakapan)
cache_read_input_tokens: 0 (tidak ada cache hit)

Untuk permintaan berikutnya dengan hanya pesan pengguna baru:

input_tokens: Token dalam pesan pengguna baru saja
cache_creation_input_tokens: Token baru apa pun yang ditambahkan ke riwayat percakapan
cache_read_input_tokens: Semua token yang sebelumnya di-cache (tools + instruksi + dokumen RAG + percakapan sebelumnya)

Pola ini sangat kuat untuk:

Aplikasi RAG dengan konteks dokumen besar
Sistem agen yang menggunakan beberapa tools
Percakapan yang berjalan lama yang perlu mempertahankan konteks
Aplikasi yang perlu mengoptimalkan bagian berbeda dari prompt secara independen

FAQ

Apakah saya perlu beberapa breakpoint cache atau satu di akhir sudah cukup?

Apakah breakpoint cache menambah biaya ekstra?

Berapa lama masa hidup cache?

Berapa banyak breakpoint cache yang dapat saya gunakan?

Apakah prompt caching tersedia untuk semua model?

Bagaimana prompt caching bekerja dengan extended thinking?

Bagaimana cara mengaktifkan prompt caching?

Bisakah saya menggunakan prompt caching dengan fitur API lainnya?

Bagaimana prompt caching mempengaruhi harga?

Bisakah saya menghapus cache secara manual?

Bagaimana saya dapat melacak efektivitas strategi caching saya?

Apa yang dapat merusak cache?

Bagaimana prompt caching menangani privasi dan pemisahan data?

Bisakah saya menggunakan prompt caching dengan Batches API?

Mengapa saya melihat error `AttributeError: 'Beta' object has no attribute 'prompt_caching'` di Python?

Error ini biasanya muncul ketika Anda telah mengupgrade SDK Anda atau Anda menggunakan contoh kode yang sudah usang. Prompt caching sekarang tersedia secara umum, jadi Anda tidak lagi memerlukan awalan beta. Alih-alih:

python client.beta.prompt_caching.messages.create(...)

Cukup gunakan:

python client.messages.create(...)

Mengapa saya melihat 'TypeError: Cannot read properties of undefined (reading 'messages')'?

TypeScript
client.beta.promptCaching.messages.create(...)

Cukup gunakan:

client.messages.create(...)

Glosarium Extended thinking

On this page

Cara kerja prompt caching
Harga
Cara mengimplementasikan prompt caching
Model yang didukung
Menyusun prompt Anda
Cara kerja pemeriksaan prefiks otomatis
Kapan menggunakan beberapa breakpoint
Keterbatasan cache
Memahami biaya breakpoint cache
Apa yang dapat di-cache
Apa yang tidak dapat di-cache
Apa yang membatalkan cache
Melacak performa cache
Praktik terbaik untuk caching yang efektif
Mengoptimalkan untuk kasus penggunaan berbeda
Mengatasi masalah umum
Caching dengan blok thinking
Penyimpanan dan berbagi cache
Durasi cache 1 jam
Kapan menggunakan cache 1 jam
Mencampur TTL yang berbeda
Contoh prompt caching
FAQ

Langkah pertama

Model & harga

Pelajari tentang Claude

Kemampuan

Alat

Model Context Protocol (MCP)

Kasus penggunaan

Rekayasa prompt

Uji & evaluasi

Perkuat pagar pengaman

Pusat Hukum

Cara kerja prompt caching

Harga

Cara mengimplementasikan prompt caching

Model yang didukung

Menyusun prompt Anda

Cara kerja pemeriksaan prefiks otomatis

Kapan menggunakan beberapa breakpoint

Keterbatasan cache

Memahami biaya breakpoint cache

Apa yang dapat di-cache

Apa yang tidak dapat di-cache

Apa yang membatalkan cache

Melacak performa cache

Praktik terbaik untuk caching yang efektif

Mengoptimalkan untuk kasus penggunaan berbeda

Mengatasi masalah umum

Caching dengan blok thinking

Penyimpanan dan berbagi cache

Durasi cache 1 jam

Kapan menggunakan cache 1 jam

Mencampur TTL yang berbeda

Contoh prompt caching

FAQ

Langkah pertama

Model & harga

Pelajari tentang Claude

Kemampuan

Alat

Model Context Protocol (MCP)

Kasus penggunaan

Rekayasa prompt

Uji & evaluasi

Perkuat pagar pengaman

Pusat Hukum

​Cara kerja prompt caching

​Harga

​Cara mengimplementasikan prompt caching

​Model yang didukung

​Menyusun prompt Anda

​Cara kerja pemeriksaan prefiks otomatis

​Kapan menggunakan beberapa breakpoint

​Keterbatasan cache

​Memahami biaya breakpoint cache

​Apa yang dapat di-cache

​Apa yang tidak dapat di-cache

​Apa yang membatalkan cache

​Melacak performa cache

​Praktik terbaik untuk caching yang efektif

​Mengoptimalkan untuk kasus penggunaan berbeda

​Mengatasi masalah umum

​Caching dengan blok thinking

​Penyimpanan dan berbagi cache

​Durasi cache 1 jam

​Kapan menggunakan cache 1 jam

​Mencampur TTL yang berbeda

​Contoh prompt caching

​FAQ

Cara kerja prompt caching

Harga

Cara mengimplementasikan prompt caching

Model yang didukung

Menyusun prompt Anda

Cara kerja pemeriksaan prefiks otomatis

Kapan menggunakan beberapa breakpoint

Keterbatasan cache

Memahami biaya breakpoint cache

Apa yang dapat di-cache

Apa yang tidak dapat di-cache

Apa yang membatalkan cache

Melacak performa cache

Praktik terbaik untuk caching yang efektif

Mengoptimalkan untuk kasus penggunaan berbeda

Mengatasi masalah umum

Caching dengan blok thinking

Penyimpanan dan berbagi cache

Durasi cache 1 jam

Kapan menggunakan cache 1 jam

Mencampur TTL yang berbeda

Contoh prompt caching

FAQ