Loading...
    • Panduan Pengembang
    • Referensi API
    • MCP
    • Sumber daya
    • Catatan Rilis
    Search...
    ⌘K
    Langkah pertama
    Pengenalan ClaudeMulai cepat
    Model & harga
    Ikhtisar modelMemilih modelYang baru di Claude 4.6Panduan migrasiPenghentian modelHarga
    Bangun dengan Claude
    Ikhtisar fiturMenggunakan Messages APIMenangani alasan berhentiPraktik terbaik prompting
    Kemampuan model
    Extended thinkingAdaptive thinkingEffortMode cepat (pratinjau penelitian)Output terstrukturKutipanStreaming MessagesPemrosesan batchDukungan PDFHasil pencarianDukungan multibahasaEmbeddingsVisi
    Alat
    IkhtisarCara mengimplementasikan penggunaan alatAlat pencarian webAlat pengambilan webAlat eksekusi kodeAlat memoriAlat BashAlat penggunaan komputerAlat editor teks
    Infrastruktur alat
    Pencarian alatPemanggilan alat terprogramStreaming alat berbutir halus
    Manajemen konteks
    Jendela konteksPemadatanPengeditan konteksPrompt cachingPenghitungan token
    File & aset
    Files API
    Agent Skills
    IkhtisarMulai cepatPraktik terbaikSkills untuk enterpriseMenggunakan Skills dengan API
    Agent SDK
    IkhtisarMulai cepatTypeScript SDKTypeScript V2 (pratinjau)Python SDKPanduan Migrasi
    MCP di API
    Konektor MCPServer MCP jarak jauh
    Claude di platform pihak ketiga
    Amazon BedrockMicrosoft FoundryVertex AI
    Prompt engineering
    IkhtisarPembuat promptGunakan template promptPenyempurna promptJadilah jelas dan langsungGunakan contoh (multishot prompting)Biarkan Claude berpikir (CoT)Gunakan tag XMLBerikan Claude peran (system prompts)Rantai prompt kompleksTips konteks panjangTips extended thinking
    Uji & evaluasi
    Tentukan kriteria kesuksesanKembangkan kasus ujiMenggunakan Alat EvaluasiMengurangi latensi
    Perkuat guardrails
    Kurangi halusinasiTingkatkan konsistensi outputMitigasi jailbreaksStreaming penolakanKurangi kebocoran promptJaga Claude tetap dalam karakter
    Administrasi dan pemantauan
    Ikhtisar Admin APIResidensi dataRuang kerjaUsage and Cost APIClaude Code Analytics APIZero Data Retention
    Console
    Log in
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...

    Solutions

    • AI agents
    • Code modernization
    • Coding
    • Customer support
    • Education
    • Financial services
    • Government
    • Life sciences

    Partners

    • Amazon Bedrock
    • Google Cloud's Vertex AI

    Learn

    • Blog
    • Catalog
    • Courses
    • Use cases
    • Connectors
    • Customer stories
    • Engineering at Anthropic
    • Events
    • Powered by Claude
    • Service partners
    • Startups program

    Company

    • Anthropic
    • Careers
    • Economic Futures
    • Research
    • News
    • Responsible Scaling Policy
    • Security and compliance
    • Transparency

    Learn

    • Blog
    • Catalog
    • Courses
    • Use cases
    • Connectors
    • Customer stories
    • Engineering at Anthropic
    • Events
    • Powered by Claude
    • Service partners
    • Startups program

    Help and security

    • Availability
    • Status
    • Support
    • Discord

    Terms and policies

    • Privacy policy
    • Responsible disclosure policy
    • Terms of service: Commercial
    • Terms of service: Consumer
    • Usage policy
    Manajemen konteks

    Prompt caching

    Optimalkan penggunaan API Anda dengan prompt caching untuk mengurangi waktu pemrosesan dan biaya.

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

    This feature qualifies for Zero Data Retention (ZDR) with limited technical retention. See the Data retention section for details on what is retained and why.

    Ada dua cara untuk mengaktifkan prompt caching:

    • Caching otomatis: Tambahkan satu field cache_control di tingkat atas permintaan Anda. Sistem secara otomatis menerapkan cache breakpoint ke blok yang dapat di-cache terakhir dan memindahkannya ke depan seiring percakapan berkembang. Terbaik untuk percakapan multi-giliran di mana riwayat pesan yang berkembang harus di-cache secara otomatis.
    • Cache breakpoint eksplisit: Tempatkan cache_control langsung pada blok konten individual untuk kontrol yang lebih detail atas apa yang di-cache.

    Cara termudah untuk memulai adalah dengan caching otomatis:

    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-6",
        "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."
          }
        ]
      }'

    Dengan caching otomatis, sistem meng-cache semua konten hingga dan termasuk blok yang dapat di-cache terakhir. Pada permintaan berikutnya dengan prefiks 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 prefiks prompt, hingga cache breakpoint 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 konteks atau informasi latar belakang yang besar
    • Tugas berulang dengan instruksi yang konsisten
    • Percakapan multi-giliran yang panjang

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

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

    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.6$5 / MTok$6.25 / MTok$10 / MTok$0.50 / MTok$25 / MTok
    Claude Opus 4.5$5 / MTok$6.25 / MTok$10 / MTok$0.50 / MTok$25 / MTok
    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.6$3 / MTok$3.75 / MTok$6 / MTok$0.30 / MTok$15 / MTok
    Claude Sonnet 4.5$3 / MTok$3.75 / MTok$6 / MTok$0.30 / MTok$15 / MTok
    Claude Sonnet 4$3 / MTok$3.75 / MTok$6 / MTok$0.30 / MTok$15 / MTok
    Claude Sonnet 3.7 (deprecated)$3 / MTok$3.75 / MTok$6 / MTok$0.30 / MTok$15 / MTok
    Claude Haiku 4.5$1 / MTok$1.25 / MTok$2 / MTok$0.10 / MTok$5 / 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 penulisan cache 5 menit adalah 1,25 kali harga token input dasar
    • Token penulisan cache 1 jam adalah 2 kali harga token input dasar
    • Token pembacaan cache adalah 0,1 kali harga token input dasar

    Pengali ini ditumpuk dengan pengubah harga lainnya seperti diskon Batch API, harga konteks panjang, dan residensi data. Lihat harga untuk detail lengkap.


    Model yang didukung

    Prompt caching (baik otomatis maupun eksplisit) saat ini didukung pada:

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

    Caching otomatis

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

    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-6",
        "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?"}
        ]
      }'

    Cara kerja caching otomatis dalam percakapan multi-giliran

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

    PermintaanKontenPerilaku cache
    Permintaan 1System
    + User(1) + Asst(1)
    + User(2) ◀ cache
    Semua ditulis ke cache
    Permintaan 2System
    + User(1) + Asst(1)
    + User(2) + Asst(2)
    + User(3) ◀ cache
    System hingga User(2) dibaca dari cache;
    Asst(2) + User(3) ditulis ke cache
    Permintaan 3System
    + User(1) + Asst(1)
    + User(2) + Asst(2)
    + User(3) + Asst(3)
    + User(4) ◀ cache
    System hingga User(3) dibaca dari cache;
    Asst(3) + User(4) ditulis ke cache

    Cache breakpoint secara otomatis berpindah ke blok yang dapat di-cache terakhir dalam setiap permintaan, sehingga Anda tidak perlu memperbarui penanda cache_control apa pun seiring percakapan berkembang.

    Dukungan TTL

    Secara default, caching otomatis menggunakan TTL 5 menit. Anda dapat menentukan TTL 1 jam dengan harga 2x token input dasar:

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

    Menggabungkan dengan caching tingkat blok

    Caching otomatis kompatibel dengan cache breakpoint eksplisit. Ketika digunakan bersama, cache breakpoint otomatis menggunakan salah satu dari 4 slot breakpoint yang tersedia.

    Ini memungkinkan Anda menggabungkan kedua pendekatan. Misalnya, gunakan breakpoint eksplisit untuk meng-cache system prompt dan tools secara independen, sementara caching otomatis menangani percakapan:

    {
      "model": "claude-opus-4-6",
      "max_tokens": 1024,
      "cache_control": {"type": "ephemeral"},
      "system": [
        {
          "type": "text",
          "text": "You are a helpful assistant.",
          "cache_control": {"type": "ephemeral"}
        }
      ],
      "messages": [...]
    }

    Yang tetap sama

    Caching otomatis menggunakan infrastruktur caching yang sama. Harga, ambang batas token minimum, persyaratan urutan 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 tidak melakukan apa-apa.
    • Jika blok terakhir memiliki cache_control eksplisit dengan TTL yang berbeda, API mengembalikan error 400.
    • Jika 4 breakpoint tingkat blok eksplisit sudah ada, API mengembalikan error 400 (tidak ada slot yang tersisa untuk caching otomatis).
    • Jika blok terakhir tidak memenuhi syarat sebagai target cache breakpoint otomatis, sistem secara diam-diam berjalan mundur untuk menemukan blok yang memenuhi syarat terdekat. Jika tidak ditemukan, caching dilewati.

    Caching otomatis tersedia di Claude API dan Azure AI Foundry (pratinjau). Dukungan untuk Amazon Bedrock dan Google Vertex AI akan hadir kemudian.


    Cache breakpoint eksplisit

    Untuk kontrol lebih atas caching, Anda dapat menempatkan cache_control langsung pada blok konten individual. Ini berguna ketika Anda perlu meng-cache bagian yang berbeda yang berubah dengan frekuensi berbeda, atau memerlukan kontrol yang lebih detail atas apa yang di-cache.

    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 di atas level sebelumnya.

    Cara kerja pemeriksaan prefiks otomatis

    Anda dapat menggunakan hanya satu cache breakpoint di akhir konten statis Anda, dan sistem akan secara otomatis menemukan urutan blok yang di-cache yang paling panjang. Memahami cara kerjanya membantu Anda mengoptimalkan strategi caching Anda.

    Tiga prinsip inti:

    1. Kunci cache bersifat kumulatif: Ketika Anda secara eksplisit meng-cache blok 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 breakpoint 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 cache_control breakpoint eksplisit. Setelah memeriksa 20 blok tanpa kecocokan, sistem berhenti memeriksa dan beralih ke breakpoint eksplisit berikutnya (jika ada).

    Contoh: Memahami jendela lookback

    Pertimbangkan percakapan dengan 30 blok konten di mana Anda menetapkan cache_control hanya pada blok 30:

    • Jika Anda mengirim blok 31 tanpa perubahan pada blok sebelumnya: Sistem memeriksa blok 30 (cocok!). Anda mendapatkan cache hit di 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 tidak berubah, Anda mendapatkan cache hit di 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 ke-20). Setelah 20 pemeriksaan tanpa menemukan kecocokan, sistem berhenti mencari. Karena blok 5 berada di luar jendela 20 blok, tidak ada cache hit yang terjadi dan semua blok perlu diproses ulang. Namun, jika Anda telah menetapkan cache_control breakpoint eksplisit pada blok 5, sistem akan terus memeriksa dari breakpoint tersebut: blok 5 (tidak cocok) → blok 4 (cocok!). Ini memungkinkan cache hit di blok 4, menunjukkan mengapa Anda harus menempatkan breakpoint sebelum konten yang dapat diedit.

    Kesimpulan utama: Selalu tetapkan cache breakpoint eksplisit di akhir percakapan Anda untuk memaksimalkan peluang cache hit. Selain itu, tetapkan breakpoint tepat sebelum blok konten yang mungkin dapat diedit untuk memastikan bagian-bagian tersebut dapat di-cache secara independen.

    Kapan menggunakan beberapa breakpoint

    Anda dapat mendefinisikan hingga 4 cache breakpoint jika Anda ingin:

    • Meng-cache bagian yang berbeda yang berubah dengan 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 akhir Anda
    • Menempatkan breakpoint sebelum konten yang dapat diedit untuk menjamin cache hit bahkan ketika perubahan terjadi di luar jendela 20 blok

    Batasan penting: Jika prompt Anda memiliki lebih dari 20 blok konten sebelum cache breakpoint Anda, dan Anda memodifikasi konten lebih awal dari 20 blok tersebut, Anda tidak akan mendapatkan cache hit kecuali Anda menambahkan breakpoint eksplisit tambahan yang lebih dekat dengan konten tersebut.

    Memahami biaya cache breakpoint

    Cache breakpoint 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 sebenarnya di-cache dan dibaca. Breakpoint hanya memberi Anda kontrol atas bagian mana yang dapat di-cache secara independen.


    Strategi dan pertimbangan caching

    Batasan cache

    Panjang prompt minimum yang dapat di-cache adalah:

    • 4096 token untuk Claude Opus 4.6, 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. Setiap permintaan untuk meng-cache kurang dari jumlah token ini akan diproses tanpa caching. Untuk melihat apakah prompt di-cache, lihat field 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.

    Apa yang dapat di-cache

    Sebagian besar blok dalam permintaan dapat di-cache. Ini termasuk:

    • Tools: Definisi tool dalam array tools
    • Pesan sistem: Blok konten dalam array system
    • Pesan teks: Blok konten dalam array messages.content, untuk giliran pengguna dan asisten
    • Gambar & Dokumen: Blok konten dalam array messages.content, dalam giliran pengguna
    • Penggunaan tool dan hasil tool: Blok konten dalam array messages.content, dalam giliran 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 thinking tidak dapat di-cache secara langsung dengan cache_control. Namun, blok thinking DAPAT di-cache bersama konten lain ketika muncul dalam giliran asisten sebelumnya. Ketika di-cache dengan cara ini, blok tersebut DIHITUNG sebagai token input ketika dibaca dari cache.

    • Sub-blok konten (seperti kutipan) itu sendiri tidak dapat di-cache secara 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 oleh kutipan.

    • Blok teks kosong tidak dapat di-cache.

    Apa yang membatalkan cache

    Modifikasi pada konten yang di-cache dapat membatalkan sebagian atau seluruh cache.

    Seperti yang dijelaskan dalam Menyusun prompt Anda, cache mengikuti hierarki: tools → system → messages. Perubahan pada 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, sementara ✓ menunjukkan bahwa cache tetap valid.

    Apa yang berubahCache toolsCache systemCache messagesDampak
    Definisi tool✘✘✘Memodifikasi definisi tool (nama, deskripsi, parameter) membatalkan seluruh cache
    Toggle pencarian web✓✘✘Mengaktifkan/menonaktifkan pencarian web memodifikasi system prompt
    Toggle kutipan✓✘✘Mengaktifkan/menonaktifkan kutipan memodifikasi system prompt
    Pengaturan kecepatan✓✘✘Beralih antara speed: "fast" dan kecepatan standar membatalkan cache sistem dan pesan
    Pilihan tool✓✓✘Perubahan pada parameter tool_choice hanya mempengaruhi blok pesan
    Gambar✓✓✘Menambahkan/menghapus gambar di mana saja dalam prompt mempengaruhi blok pesan
    Parameter thinking✓✓✘Perubahan pada pengaturan extended thinking (aktifkan/nonaktifkan, 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 dalam 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 (yaitu, token setelah cache breakpoint terakhir).

    Memahami rincian token

    Field input_tokens hanya mewakili token yang datang setelah cache breakpoint terakhir dalam permintaan Anda - bukan semua token input yang Anda kirim.

    Untuk menghitung total token input:

    total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens

    Penjelasan spasial:

    • cache_read_input_tokens = token sebelum breakpoint yang sudah di-cache (pembacaan)
    • cache_creation_input_tokens = token sebelum breakpoint yang sedang di-cache sekarang (penulisan)
    • input_tokens = token setelah breakpoint terakhir Anda (tidak memenuhi syarat untuk cache)

    Contoh: Jika Anda memiliki permintaan dengan 100.000 token konten yang di-cache (dibaca dari cache), 0 token konten baru yang sedang di-cache, dan 50 token dalam pesan pengguna Anda (setelah cache breakpoint):

    • cache_read_input_tokens: 100.000
    • cache_creation_input_tokens: 0
    • input_tokens: 50
    • Total token input yang diproses: 100.050 token

    Ini penting untuk memahami biaya dan batas rate, karena input_tokens biasanya akan jauh lebih kecil dari total input Anda saat menggunakan caching secara efektif.

    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, blok tersebut di-cache sebagai bagian dari konten permintaan ketika Anda melakukan panggilan API berikutnya dengan hasil tool. Ini umumnya terjadi selama penggunaan tool ketika Anda meneruskan blok thinking kembali untuk melanjutkan percakapan.

    Penghitungan token input: Ketika blok thinking dibaca dari cache, blok tersebut dihitung sebagai token input dalam metrik penggunaan Anda. Ini penting untuk perhitungan biaya dan penganggaran token.

    Pola pembatalan cache:

    • Cache tetap valid ketika hanya hasil tool yang disediakan sebagai pesan pengguna
    • Cache dibatalkan ketika konten pengguna non-hasil-tool 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:

    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-hasil-tool disertakan, blok tersebut menandai loop asisten baru dan semua blok thinking sebelumnya dihapus dari konteks.

    Untuk informasi lebih detail, lihat dokumentasi extended thinking.

    Penyimpanan dan berbagi cache

    Mulai 5 Februari 2026, prompt caching akan menggunakan isolasi tingkat workspace alih-alih isolasi tingkat organisasi. Cache akan diisolasi per workspace, memastikan pemisahan data antar workspace dalam organisasi yang sama. Perubahan ini berlaku untuk Claude API dan Azure AI Foundry (pratinjau); Amazon Bedrock dan Google Vertex AI akan mempertahankan isolasi cache tingkat organisasi. Jika Anda menggunakan beberapa workspace, tinjau strategi caching Anda untuk memperhitungkan perubahan ini.

    • 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 cache control.

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

    Praktik terbaik untuk caching yang efektif

    Untuk mengoptimalkan performa prompt caching:

    • Mulai dengan caching otomatis untuk percakapan multi-giliran. Ini menangani manajemen breakpoint secara otomatis.
    • Gunakan breakpoint tingkat blok eksplisit ketika Anda perlu meng-cache bagian yang berbeda dengan frekuensi perubahan yang berbeda.
    • 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 cache breakpoint secara strategis untuk memisahkan bagian prefiks yang dapat di-cache yang berbeda.
    • Tetapkan cache breakpoint 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.
    • Analisis tingkat cache hit secara teratur dan sesuaikan strategi Anda sesuai kebutuhan.

    Mengoptimalkan untuk berbagai kasus penggunaan

    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 tanya jawab codebase dengan menyimpan bagian yang relevan atau versi ringkasan dari codebase dalam prompt.
    • Pemrosesan dokumen besar: Gabungkan materi 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 prompt caching Anda dapat mendapatkan performa yang lebih baik dengan menyertakan 20+ contoh jawaban berkualitas tinggi yang beragam.
    • 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 panjang lainnya: Hidupkan basis pengetahuan apa pun dengan menyematkan seluruh dokumen ke dalam prompt, dan biarkan pengguna mengajukan pertanyaan.

    Memecahkan masalah umum

    Jika mengalami perilaku yang tidak terduga:

    • Pastikan bagian yang di-cache identik di seluruh panggilan. Untuk breakpoint eksplisit, verifikasi bahwa penanda cache_control berada di lokasi yang sama
    • Periksa bahwa panggilan dilakukan dalam masa hidup cache (5 menit secara default)
    • Verifikasi bahwa penggunaan tool_choice dan 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 memerlukan parameter cache_control tambahan lebih awal dalam prompt untuk memastikan semua konten dapat di-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, merusak cache

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


    Durasi cache 1 jam

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

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

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

    Respons akan menyertakan informasi cache terperinci seperti berikut:

    {
      "usage": {
        "input_tokens": 2048,
        "cache_read_input_tokens": 1800,
        "cache_creation_input_tokens": 248,
        "output_tokens": 503,
    
        "cache_creation": {
          "ephemeral_5m_input_tokens": 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 secara teratur (yaitu, system prompt yang digunakan lebih sering dari setiap 5 menit), terus gunakan 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 dari 5 menit, tetapi lebih sering dari setiap jam. Misalnya, ketika agen sisi agentic akan membutuhkan 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 tindak lanjut Anda mungkin dikirim lebih dari 5 menit.
    • Ketika Anda ingin meningkatkan utilisasi batas rate Anda, karena cache hit tidak dikurangkan dari batas rate Anda.

    Cache 5 menit dan 1 jam berperilaku sama sehubungan dengan 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 lama 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, keduanya pasti merupakan cache miss, karena A adalah cache hit tertinggi.

    Anda akan dikenakan biaya untuk:

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

    Berikut adalah 3 contoh. Ini menggambarkan token input dari 3 permintaan, masing-masing memiliki cache hit dan cache miss yang berbeda. Masing-masing memiliki harga yang dihitung berbeda, ditampilkan dalam kotak berwarna, sebagai hasilnya. Diagram Pencampuran TTL


    Contoh prompt caching

    Untuk membantu Anda memulai dengan prompt caching, kami telah menyiapkan sebuah buku masak prompt caching dengan contoh-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 berbagai skenario, membantu Anda memahami aplikasi praktis dari fitur ini:

    Retensi data

    Prompt caching menyimpan representasi cache KV (key-value) dan hash kriptografis dari konten yang di-cache, tetapi tidak menyimpan teks mentah dari prompt atau respons. Entri cache memiliki masa hidup minimum 5 menit (standar) atau 60 menit (diperpanjang). Entri cache diisolasi antar organisasi. Karena Anthropic tidak menyimpan teks prompt atau respons mentah, fitur ini mungkin cocok untuk pelanggan yang memerlukan komitmen retensi data tipe ZDR.

    Untuk kelayakan ZDR di semua fitur, lihat API dan Retensi Data.


    FAQ

    Was this page helpful?

    • Cara kerja prompt caching
    • Harga
    • Model yang didukung
    • Caching otomatis
    • Cara kerja caching otomatis dalam percakapan multi-giliran
    • Dukungan TTL
    • Menggabungkan dengan caching tingkat blok
    • Yang tetap sama
    • Kasus tepi
    • Cache breakpoint eksplisit
    • Menyusun prompt Anda
    • Memahami biaya cache breakpoint
    • Strategi dan pertimbangan caching
    • Batasan cache
    • Apa yang dapat di-cache
    • Apa yang tidak dapat di-cache
    • Apa yang membatalkan cache
    • Melacak performa cache
    • Caching dengan blok thinking
    • Penyimpanan dan berbagi cache
    • Praktik terbaik untuk caching yang efektif
    • Mengoptimalkan untuk berbagai kasus penggunaan
    • Memecahkan masalah umum
    • Durasi cache 1 jam
    • Kapan menggunakan cache 1 jam
    • Mencampur TTL yang berbeda
    • Contoh prompt caching
    • Retensi data
    • FAQ