Prompt caching

Sebagian besar request berulang: system prompt yang sama, definisi tool yang sama, dokumen panjang yang sama, percakapan yang sama sejauh ini. Prompt caching memungkinkan model menggunakan kembali pekerjaan yang sudah dilakukannya pada bagian awal yang berulang itu, dan Anda hanya membayar sebagian kecil dari harga input untuk bagian yang ter-cache.

Fitur ini paling berpengaruh untuk coding agent dan aplikasi chat, yang mengirim ulang hampir seluruh konteksnya di setiap giliran.

Cara penetapan harga

Setiap model yang mendukung caching memiliki harga cached_input di samping harga inputnya, di daftar model dan di halaman model. Misalnya, claude-sonnet-4-6 mengenakan biaya $3 per 1M token input dan $0.30 per 1M token input ter-cache. Beberapa model juga mengenakan biaya lebih tinggi dari harga input untuk menulis entri cache pertama kali; halaman model tersebut mencantumkannya.

Token ter-cache muncul di data penggunaan, dan di log request Anda:

"usage": {
  "prompt_tokens": 12850,
  "completion_tokens": 210,
  "prompt_tokens_details": { "cached_tokens": 12288 }
}

Pada endpoint Messages, token tersebut adalah cache_read_input_tokens dan cache_creation_input_tokens.

Caching otomatis

Banyak model — termasuk keluarga GPT, Gemini, DeepSeek, dan Kimi — melakukan caching secara otomatis. Anda tidak perlu mengubah apa pun: saat sebuah request diawali dengan token yang sama seperti request terbaru, prefix yang sama tersebut disajikan dari cache. Untuk mendapatkan hasil maksimal:

• Letakkan bagian yang tetap di awal: system prompt, definisi tool, dokumen referensi.
• Letakkan bagian yang berubah di akhir: pesan pengguna terbaru.
• Jangan masukkan timestamp atau ID request ke dalam system prompt; satu token yang berubah di awal akan memutus kecocokan untuk semua token setelahnya.

Caching eksplisit dengan cache_control

Model Claude hanya melakukan caching pada bagian yang Anda tandai. Tambahkan breakpoint cache_control pada blok terakhir dari bagian yang ingin digunakan kembali, dan semua bagian hingga titik tersebut akan di-cache:

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "system": [
    {
      "type": "text",
      "text": "You are a support agent for Acme. Here is the full product manual: ...",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [{ "role": "user", "content": "How do I reset the device?" }]
}

Penanda yang sama juga berfungsi di Chat Completions, pada bagian teks sebuah pesan:

{
  "role": "system",
  "content": [
    { "type": "text", "text": "Long, stable instructions...", "cache_control": { "type": "ephemeral" } }
  ]
}

• Secara default, entri cache bertahan lima menit dan diperbarui setiap kali digunakan. "ttl": "1h" menyimpannya selama satu jam, dengan harga penulisan yang lebih tinggi.
• Maksimal empat breakpoint per request. Menandai definisi tool dan system prompt secara terpisah memungkinkan salah satunya berubah tanpa kehilangan cache yang lain.
• Di bawah panjang minimum yang spesifik untuk tiap model (sekitar 1.024 token untuk sebagian besar model Claude), tidak ada yang di-cache. Request tetap berhasil.

Claude Code dan sebagian besar coding agent menetapkan penanda ini untuk Anda.

Memastikan caching berfungsi

Kirim prompt panjang yang sama dua kali dalam rentang beberapa menit. Respons kedua seharusnya melaporkan sebagian besar prompt sebagai token ter-cache. Jika tidak melaporkan apa pun, cari sesuatu yang berubah di awal prompt di antara kedua request tersebut.