Penyimpanan cache prompt

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-sonnet-4-5",
    "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

{"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}

​

Cara kerja penyimpanan cache prompt

1. Sistem memeriksa apakah awalan prompt, hingga titik henti cache yang ditentukan, sudah disimpan dalam cache dari kueri baru-baru ini.
2. Jika ditemukan, sistem menggunakan versi yang disimpan dalam cache, mengurangi waktu pemrosesan dan biaya.
3. Jika tidak, sistem memproses prompt lengkap dan menyimpan awalan dalam cache setelah respons dimulai.

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

​

Harga

​

Cara mengimplementasikan penyimpanan cache prompt

​

Model yang didukung

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

​

Menyusun prompt Anda

​

Cara kerja pemeriksaan awalan otomatis

1. Kunci cache bersifat kumulatif: Ketika Anda secara eksplisit menyimpan blok dalam cache dengan cache_control, kunci hash cache dihasilkan dengan melakukan hash semua blok sebelumnya dalam percakapan secara berurutan. Ini berarti cache untuk setiap blok bergantung pada semua konten yang datang sebelumnya.
2. Pemeriksaan berurutan mundur: Sistem memeriksa cache hit dengan bekerja mundur dari titik henti eksplisit Anda, memeriksa setiap blok sebelumnya dalam urutan terbalik. Ini memastikan Anda mendapatkan cache hit terpanjang yang mungkin.
3. Jendela lookback 20 blok: Sistem hanya memeriksa hingga 20 blok sebelum setiap titik henti cache_control eksplisit. Setelah memeriksa 20 blok tanpa kecocokan, sistem berhenti memeriksa dan beralih ke titik henti eksplisit berikutnya (jika ada).

• Jika Anda mengirim blok 31 tanpa perubahan pada blok sebelumnya: Sistem memeriksa blok 30 (cocok!). Anda mendapatkan cache hit pada blok 30, dan hanya blok 31 yang perlu diproses.
• Jika Anda memodifikasi blok 25 dan mengirim blok 31: Sistem memeriksa mundur dari blok 30 → 29 → 28… → 25 (tidak cocok) → 24 (cocok!). Karena blok 24 belum berubah, Anda mendapatkan cache hit pada blok 24, dan hanya blok 25-30 yang perlu diproses ulang.
• Jika Anda memodifikasi blok 5 dan mengirim blok 31: Sistem memeriksa mundur dari blok 30 → 29 → 28… → 11 (pemeriksaan #20). Setelah 20 pemeriksaan tanpa menemukan kecocokan, sistem berhenti mencari. Karena blok 5 berada di luar jendela 20 blok, tidak ada cache hit dan semua blok perlu diproses ulang. Namun, jika Anda telah menetapkan titik henti cache_control eksplisit pada blok 5, sistem akan terus memeriksa dari titik henti itu: blok 5 (tidak cocok) → blok 4 (cocok!). Ini memungkinkan cache hit pada blok 4, menunjukkan mengapa Anda harus menempatkan titik henti sebelum konten yang dapat diedit.

​

Kapan menggunakan beberapa titik henti

• Menyimpan bagian berbeda yang berubah pada frekuensi berbeda dalam cache (misalnya, alat jarang berubah, tetapi konteks diperbarui setiap hari)
• Memiliki kontrol lebih besar atas apa yang disimpan dalam cache
• Memastikan penyimpanan cache untuk konten lebih dari 20 blok sebelum titik henti cache Anda
• Menempatkan titik henti sebelum konten yang dapat diedit untuk menjamin cache hit bahkan ketika perubahan terjadi di luar jendela 20 blok

​

Batasan cache

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

​

Memahami biaya titik henti cache

• Penulisan cache: Ketika konten baru ditulis ke cache (25% lebih banyak dari token input dasar untuk TTL 5 menit)
• Pembacaan cache: Ketika konten yang disimpan dalam cache digunakan (10% dari harga token input dasar)
• Token input reguler: Untuk konten apa pun yang tidak disimpan dalam cache

​

Apa yang dapat disimpan dalam cache

• 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

​

Apa yang tidak dapat disimpan dalam cache

• Blok pemikiran tidak dapat disimpan dalam cache secara langsung dengan cache_control. Namun, blok pemikiran DAPAT disimpan dalam cache bersama konten lain ketika muncul dalam putaran asisten sebelumnya. Ketika disimpan dengan cara ini, mereka MENGHITUNG sebagai token input ketika dibaca dari cache.
• Blok sub-konten (seperti citations) itu sendiri tidak dapat disimpan dalam cache secara langsung. Sebagai gantinya, simpan blok tingkat atas dalam cache. Dalam kasus kutipan, blok konten dokumen tingkat atas yang berfungsi sebagai materi sumber untuk kutipan dapat disimpan dalam cache. Ini memungkinkan Anda menggunakan penyimpanan cache prompt dengan kutipan secara efektif dengan menyimpan dokumen yang akan direferensikan oleh kutipan dalam cache.
• Blok teks kosong tidak dapat disimpan dalam cache.

​

Apa yang membatalkan cache

​

Melacak kinerja cache

• 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 penyimpanan cache yang efektif

• Simpan konten stabil dan dapat digunakan kembali seperti instruksi sistem, informasi latar belakang, konteks besar, atau definisi alat yang sering digunakan dalam cache.
• Tempatkan konten yang disimpan dalam cache di awal prompt untuk kinerja terbaik.
• Gunakan titik henti cache secara strategis untuk memisahkan bagian awalan yang berbeda yang dapat disimpan dalam cache.
• Tetapkan titik henti cache di akhir percakapan dan tepat sebelum konten yang dapat diedit untuk memaksimalkan tingkat cache hit, terutama saat bekerja dengan prompt yang memiliki lebih dari 20 blok konten.
• Secara teratur analisis tingkat cache hit dan sesuaikan strategi Anda sesuai kebutuhan.

​

Mengoptimalkan untuk kasus penggunaan yang berbeda

• Agen percakapan: Kurangi biaya dan latensi untuk percakapan yang diperpanjang, terutama yang memiliki instruksi panjang atau dokumen yang diunggah.
• Asisten pengkodean: Tingkatkan pelengkapan otomatis dan Q&A basis kode dengan menyimpan bagian yang relevan atau versi ringkasan basis kode dalam prompt.
• Pemrosesan dokumen besar: Gabungkan materi bentuk panjang lengkap termasuk gambar dalam prompt Anda tanpa meningkatkan latensi respons.
• Set instruksi terperinci: Bagikan daftar instruksi, prosedur, dan contoh yang luas untuk menyempurnakan respons Claude. Pengembang sering menyertakan satu atau dua contoh dalam prompt, tetapi dengan penyimpanan cache prompt Anda dapat mencapai kinerja yang lebih baik dengan menyertakan 20+ contoh beragam jawaban berkualitas tinggi.
• Penggunaan alat agentic: Tingkatkan kinerja untuk skenario yang melibatkan beberapa panggilan alat dan perubahan kode berulang, 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 kepadanya.

​

Pemecahan masalah masalah umum

• Pastikan bagian yang disimpan dalam cache identik dan ditandai dengan cache_control di lokasi yang sama di seluruh panggilan
• Periksa bahwa panggilan dilakukan dalam masa pakai cache (5 menit secara default)
• Verifikasi bahwa tool_choice dan penggunaan gambar tetap konsisten di antara panggilan
• Validasi bahwa Anda menyimpan setidaknya jumlah token minimum dalam cache
• Sistem secara otomatis memeriksa cache hit pada batas blok konten sebelumnya (hingga ~20 blok sebelum titik henti Anda). Untuk prompt dengan lebih dari 20 blok konten, Anda mungkin memerlukan parameter cache_control tambahan lebih awal dalam prompt untuk memastikan semua konten dapat disimpan dalam cache
• 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, memecahkan cache

​

Penyimpanan cache dengan blok pemikiran

• Cache tetap valid ketika hanya hasil alat yang disediakan sebagai pesan pengguna
• Cache dibatalkan ketika konten pengguna non-hasil-alat ditambahkan, menyebabkan semua blok pemikiran sebelumnya dihapus
• Perilaku penyimpanan cache ini terjadi bahkan tanpa penanda cache_control eksplisit

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

​

Penyimpanan cache dan berbagi

• Isolasi Organisasi: Cache terisolasi antara 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.
• Pembuatan Token Output: Penyimpanan cache prompt tidak memiliki efek pada pembuatan token output. Respons yang Anda terima akan identik dengan apa yang Anda dapatkan jika penyimpanan cache prompt tidak digunakan.

​

Durasi cache 1 jam

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

{
    "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,
        }
    }
}

​

Kapan menggunakan cache 1 jam

• 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 obrolan panjang dengan pengguna dan Anda umumnya mengharapkan pengguna itu mungkin tidak merespons dalam 5 menit berikutnya.
• Ketika latensi penting dan prompt tindak lanjut Anda mungkin dikirim di luar 5 menit.
• Ketika Anda ingin meningkatkan pemanfaatan batas laju Anda, karena cache hit tidak dikurangkan dari batas laju Anda.

​

Mencampur TTL yang berbeda

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.

1. Token pembacaan cache untuk A.
2. Token penulisan cache 1 jam untuk (B - A).
3. Token penulisan cache 5 menit untuk (C - B).

​

Contoh penyimpanan cache prompt

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-sonnet-4-5",
    "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?"
        }
    ]
}'

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-sonnet-4-5",
    "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?"
        }
    ]
}'

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-sonnet-4-5",
    "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"}
                }
            ]
        }
    ]
}'

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-sonnet-4-5",
    "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"}
                }
            ]
        }
    ]
}'

​

FAQ

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

python client.messages.create(...)

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

client.messages.create(...)