Panduan Penggunaan Cache Konteks Claude

Cache konteks Claude (Context Cache) cocok untuk menggunakan kembali prefiks panjang seperti system prompt, dokumen, basis kode, atau riwayat percakapan. Setelah Anda menambahkan cache_control ke prefiks stabil, permintaan pertama akan membuat cache dan permintaan berikutnya dapat membaca cache tersebut selama belum kedaluwarsa. Sebelum memulai, tetapkan kunci API Anda:

export API_KEY="KUNCI_API_ANDA"

Contoh dalam panduan ini menggunakan claude-sonnet-5. Untuk mengetahui apakah model lain mendukung cache konteks, lihat deskripsi model di platform.

Kasus penggunaan

Jika beberapa permintaan berulang kali menyertakan blok konten besar yang sama, Anda dapat menyimpan prefiks stabil ke cache, misalnya:

System prompt yang panjang
Basis pengetahuan tetap atau dokumentasi produk
Riwayat percakapan multi-giliran yang tetap sama
Basis kode, definisi tool, dan petunjuk yang digunakan kembali

Cache konteks cocok untuk permintaan dengan konten awal yang tetap sama sementara pertanyaan terakhir terus berubah.

API Claude Messages

Cache 5 menit

Tambahkan cache_control ke blok konten yang ingin disimpan ke cache:

curl "https://api.apimart.ai/v1/messages" \
  -H "x-api-key: $API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "Tempatkan prefiks panjang yang akan digunakan berulang kali di sini…",
        "cache_control": {
          "type": "ephemeral"
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Jawab pertanyaan berdasarkan konten di atas."
      }
    ]
  }'

system harus berupa array blok konten. cache_control tidak dapat ditambahkan jika system berupa string.

Jika ttl dihilangkan, masa berlaku default cache adalah 5 menit.

Cache 1 jam

Untuk menggunakan cache 1 jam, tambahkan juga header permintaan anthropic-beta dan atur ttl ke 1h:

curl "https://api.apimart.ai/v1/messages" \
  -H "x-api-key: $API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: extended-cache-ttl-2025-04-11" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "Tempatkan prefiks panjang yang akan digunakan berulang kali di sini…",
        "cache_control": {
          "type": "ephemeral",
          "ttl": "1h"
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Jawab pertanyaan berdasarkan konten di atas."
      }
    ]
  }'

TTL yang didukung:

TTL	Arti
`5m`	Cache selama 5 menit; nilai ini digunakan jika `ttl` dihilangkan
`1h`	Cache selama 1 jam; header `anthropic-beta` yang sesuai juga harus ditambahkan

Kolom penggunaan dalam respons

API Claude Messages mengembalikan token input biasa, penulisan cache, dan pembacaan cache secara terpisah di dalam usage:

{
  "usage": {
    "input_tokens": 23,
    "cache_creation_input_tokens": 2619,
    "cache_read_input_tokens": 0,
    "cache_creation": {
      "ephemeral_5m_input_tokens": 2619,
      "ephemeral_1h_input_tokens": 0
    },
    "output_tokens": 24
  }
}

Total token input dihitung sebagai berikut:

input_tokens
+ cache_creation_input_tokens
+ cache_read_input_tokens

Ketiga nilai ini tidak saling tumpang tindih. Permintaan pertama biasanya menampilkan cache_creation_input_tokens > 0; saat prefiks stabil yang sama dikirim lagi, Anda seharusnya melihat cache_read_input_tokens > 0.

API yang kompatibel dengan OpenAI

Contoh permintaan

Saat menggunakan cache melalui /v1/chat/completions, sintaks cache_control serupa dengan API Claude Messages:

curl "https://api.apimart.ai/v1/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "system",
        "content": [
          {
            "type": "text",
            "text": "Tempatkan prefiks panjang yang akan digunakan berulang kali di sini…",
            "cache_control": {
              "type": "ephemeral"
            }
          }
        ]
      },
      {
        "role": "user",
        "content": "Jawab pertanyaan berdasarkan konten di atas."
      }
    ]
  }'

Cache 1 jam

Format yang kompatibel dengan OpenAI juga mendukung cache 1 jam. Cukup tambahkan header permintaan anthropic-beta dan atur ttl: "1h" di dalam cache_control:

-H "anthropic-beta: extended-cache-ttl-2025-04-11"

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

`content` harus berupa array

Dalam format yang kompatibel dengan OpenAI, cache_control harus berada di dalam blok konten tertentu. Kolom ini tidak dapat ditempelkan ke pesan dengan konten berupa string.

{
  "role": "system",
  "content": "Tempatkan prefiks panjang di sini…",
  "cache_control": {
    "type": "ephemeral"
  }
}

Sintaks di atas tidak mengaktifkan cache, tetapi permintaan juga tidak akan menghasilkan error. Berikut adalah sintaks yang benar:

{
  "role": "system",
  "content": [
    {
      "type": "text",
      "text": "Tempatkan prefiks panjang di sini…",
      "cache_control": {
        "type": "ephemeral"
      }
    }
  ]
}

Jika content berupa string, penanda cache akan diabaikan dan konten input tetap diproses sebagai input biasa. Periksa kolom penggunaan cache dalam respons untuk memastikan apakah cache berhasil dibaca.

Menyimpan blok konten `user` atau `assistant` ke cache

Anda juga dapat menempatkan cache_control di blok konten pesan user atau assistant untuk menyimpan dokumen panjang atau prefiks percakapan multi-giliran ke cache:

{
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": "Tempatkan dokumen panjang yang akan digunakan kembali di sini…",
      "cache_control": {
        "type": "ephemeral"
      }
    },
    {
      "type": "text",
      "text": "Ringkas tiga poin utama dalam dokumen di atas."
    }
  ]
}

Pisahkan konten stabil dan pertanyaan saat ini ke dalam blok konten yang berbeda, lalu tambahkan cache_control hanya ke blok konten stabil.

Kolom penggunaan dalam respons

Format yang kompatibel dengan OpenAI menggunakan kolom yang berbeda untuk melaporkan penggunaan cache:

{
  "usage": {
    "prompt_tokens": 1942,
    "completion_tokens": 22,
    "prompt_tokens_details": {
      "cached_tokens": 1921,
      "cache_write_tokens": 0
    },
    "claude_cache_creation_5_m_tokens": 0,
    "claude_cache_creation_1_h_tokens": 0
  }
}

Pemetaan kolom:

Arti	API Claude Messages	API yang kompatibel dengan OpenAI
Total input	Jumlah dari ketiga kolom input	`prompt_tokens`
Pembacaan cache	`cache_read_input_tokens`	`prompt_tokens_details.cached_tokens`
Kolom umum penulisan cache	`cache_creation_input_tokens`	`prompt_tokens_details.cache_write_tokens` (hanya berisi nilai jika tidak ada perincian TTL)
Penulisan cache 5 menit	`cache_creation.ephemeral_5m_input_tokens`	`claude_cache_creation_5_m_tokens`
Penulisan cache 1 jam	`cache_creation.ephemeral_1h_input_tokens`	`claude_cache_creation_1_h_tokens`
Output	`output_tokens`	`completion_tokens`

Jika prompt_tokens_details.cache_write_tokens bernilai 0, tetap periksa claude_cache_creation_5_m_tokens dan claude_cache_creation_1_h_tokens. Jika kolom perincian TTL tersedia, jumlah penulisan cache akan dikembalikan melalui kolom yang sesuai.

Di dalam claude_cache_creation_5_m_tokens dan claude_cache_creation_1_h_tokens, terdapat garis bawah antara angka dan satuan. Gunakan nama kolom persis seperti yang dikembalikan dalam respons.

API yang kompatibel dengan OpenAI dapat mengembalikan respons streaming SSE meskipun Anda tidak secara eksplisit mengirimkan stream: true. Klien harus dapat mengurai chat.completion.chunk. Informasi penggunaan berada di blok data terakhir yang berisi usage.

Syarat agar cache dibaca

Prefiks mencapai panjang minimum

Prefiks cache untuk model dalam contoh biasanya harus memiliki setidaknya sekitar 1024 token. Jika prefiks terlalu pendek, penanda cache dapat diabaikan tanpa menghasilkan error.

Prefiks tetap identik byte demi byte

Teks, spasi, baris baru, dan urutan blok konten dalam prefiks cache harus tetap sama. Jangan tambahkan konten dinamis seperti stempel waktu, ID acak, atau penghitung permintaan ke prefiks stabil.

Permintaan tidak memicu penolakan model

Jika permintaan memicu penolakan model, respons mungkin masih melaporkan token pembuatan cache, tetapi cache tersebut tidak akan dibaca pada permintaan berikutnya. Saat mencari penyebab cache tidak dibaca, periksa juga apakah stop_reason bernilai refusal.

Cache masih berlaku

Masa berlaku cache adalah 5 menit atau 1 jam dan dihitung sejak akses terakhir. Pembacaan cache akan memperbarui masa berlakunya.

Penggunaan untuk penagihan

Penggunaan terkait cache dibagi menjadi tiga kategori:

Penggunaan	Waktu terjadinya
Penulisan cache	Saat cache pertama kali dibuat
Pembacaan cache	Saat permintaan berikutnya menemukan cache
Input biasa	Untuk input di luar prefiks cache

Ketiga kategori penggunaan tersebut tidak saling tumpang tindih. Penulisan cache biasanya lebih mahal daripada input biasa, sedangkan pembacaan cache biasanya lebih murah. Oleh karena itu, cache konteks lebih sesuai untuk prefiks stabil yang akan digunakan kembali selama TTL.

Contoh minimal yang dapat direproduksi

Skrip berikut terlebih dahulu membuat prefiks stabil yang cukup panjang, lalu mengirim permintaan yang sama dua kali. Respons kedua seharusnya menampilkan cache_read_input_tokens > 0.

python3 - <<'PY' > /tmp/claude-cache-request.json
import json

paragraph = (
    "Prompt caching stores a prefix of the request so that later requests "
    "can reuse the same byte-identical prefix without processing it again. "
)

system_text = (
    "You are a documentation assistant. Reference material follows.\n\n"
    + paragraph * 40
)

print(json.dumps({
    "model": "claude-sonnet-5",
    "max_tokens": 32,
    "system": [{
        "type": "text",
        "text": system_text,
        "cache_control": {"type": "ephemeral"}
    }],
    "messages": [{
        "role": "user",
        "content": "In one sentence, what must remain unchanged?"
    }]
}))
PY

for request_number in 1 2; do
  echo "Permintaan ${request_number}"
  curl -s "https://api.apimart.ai/v1/messages" \
    -H "x-api-key: $API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "Content-Type: application/json" \
    --data @/tmp/claude-cache-request.json \
  | python3 -c "import json, sys; print(json.load(sys.stdin)['usage'])"
done

Hasil yang diharapkan:

Permintaan 1: cache_creation_input_tokens > 0, cache_read_input_tokens = 0
Permintaan 2: cache_creation_input_tokens = 0, cache_read_input_tokens > 0

Daftar periksa pemecahan masalah

Jika cache tidak dibaca, periksa item berikut secara berurutan:

Apakah stop_reason bernilai refusal?
Apakah prefiks cache mencapai jumlah minimum token yang diwajibkan model?
Apakah prefiks stabil dari kedua permintaan identik byte demi byte?
Dalam format yang kompatibel dengan OpenAI, apakah content berupa array?
Apakah cache_control berada di dalam blok konten tertentu?
Untuk cache 1 jam, apakah ttl: "1h" dan header anthropic-beta yang sesuai telah ditetapkan?
Apakah cache telah melewati TTL?
Apakah Anda membaca kolom penggunaan cache yang sesuai dengan API saat ini?

Ikhtisar

Seri Teks

Seri Gambar

Seri Video

Seri Audio

Seri Moderasi

Manajemen Unggahan

Manajemen Tugas

Manajemen Akun

Panduan Penggunaan Cache Konteks Claude

Kasus penggunaan

API Claude Messages

Cache 5 menit

Cache 1 jam

Kolom penggunaan dalam respons

API yang kompatibel dengan OpenAI

Contoh permintaan

Cache 1 jam

`content` harus berupa array

Menyimpan blok konten `user` atau `assistant` ke cache

Kolom penggunaan dalam respons

Syarat agar cache dibaca

Prefiks mencapai panjang minimum

Prefiks tetap identik byte demi byte

Permintaan tidak memicu penolakan model

Cache masih berlaku

Penggunaan untuk penagihan

Contoh minimal yang dapat direproduksi

Daftar periksa pemecahan masalah

​Kasus penggunaan

​API Claude Messages

​Cache 5 menit

​Cache 1 jam

​Kolom penggunaan dalam respons

​API yang kompatibel dengan OpenAI

​Contoh permintaan

​Cache 1 jam

​content harus berupa array

​Menyimpan blok konten user atau assistant ke cache

​Kolom penggunaan dalam respons

​Syarat agar cache dibaca

​Prefiks mencapai panjang minimum

​Prefiks tetap identik byte demi byte

​Permintaan tidak memicu penolakan model

​Cache masih berlaku

​Penggunaan untuk penagihan

​Contoh minimal yang dapat direproduksi

​Daftar periksa pemecahan masalah

Kasus penggunaan

API Claude Messages

Cache 5 menit

Cache 1 jam

Kolom penggunaan dalam respons

API yang kompatibel dengan OpenAI

Contoh permintaan

Cache 1 jam

`content` harus berupa array

Menyimpan blok konten `user` atau `assistant` ke cache

Kolom penggunaan dalam respons

Syarat agar cache dibaca

Prefiks mencapai panjang minimum

Prefiks tetap identik byte demi byte

Permintaan tidak memicu penolakan model

Cache masih berlaku

Penggunaan untuk penagihan

Contoh minimal yang dapat direproduksi

Daftar periksa pemecahan masalah