Panduan Biaya Prompt Caching: Cache Hits, Prefixes, dan Pengeluaran API Aktual

Biaya prompt caching bergantung pada apakah permintaan kedua Anda terlihat persis seperti yang pertama, bukan pada diskon utama yang diiklankan. Dalam estimasi kami untuk system prompt 20.000 token pada claude-sonnet-5, 1.000 permintaan memakan biaya sekitar $18,18 tanpa cache dan sekitar $2,00 jika setiap permintaan setelah yang pertama mengenai cache. Prompt yang sama akan memakan biaya lebih mahal daripada baseline tanpa cache jika prefiks berubah pada setiap panggilan. Panduan ini menggunakan harga TokenLab yang diamati pada 2026-10-03 untuk menunjukkan di mana batas tersebut berada, dan menandai apa yang tidak dapat kami konfirmasi dalam dokumentasi.

Poin Utama

• Pada lima model yang kami periksa, pembacaan cache memakan biaya 2% hingga 10% dari harga input normal. Dua dari lima model tidak mencantumkan harga penulisan cache.
• Jika harga penulisan tersedia, harganya setara dengan input (deepseek-v4.1-flash) atau 1,25 kali harga input (claude-sonnet-5, claude-sonnet-5-5).
• Menurut perhitungan kami, satu cache hit per penulisan akan mengganti premi penulisan 1,25x. Itu mengasumsikan entri cache masih aktif, dan masa pakai cache tidak didokumentasikan dalam bukti yang kami baca.
• Caching hanya mengurangi sisi input dari tagihan. Token output tetap diberi harga seperti sebelumnya.
• Dokumentasi API TokenLab yang kami baca tidak menyebutkan field cached-token dalam usage. Catat (log) objek mentah dari pengujian Anda sendiri dan rekonsiliasikan dengan Usage.

Biaya prompt caching berdasarkan model: harga baca, tulis, dan input

Kami membaca API model langsung untuk setiap model di bawah ini pada 2026-10-03. Kelima model mencantumkan prompt-cache dalam kapabilitasnya, dan harga terakhir diperbarui pada 2026-10-02T16:53:30.068Z. Harga dalam USD per 1 juta token.

Model	Input	Cache read	Cache write	Read sebagai bagian dari input	Write vs input
claude-sonnet-5	0,90	0,09	1,125	10%	1,25x
claude-sonnet-5-5	0,60	0,06	0,75	10%	1,25x
gpt-5.5	1,50	0,15	tidak tercantum	10%	tidak tercantum
deepseek-v4.1-flash (off-peak)	0,15	0,003	0,15	2%	1,0x
deepseek-v4.1-flash (peak)	0,30	0,006	0,30	2%	1,0x
gemini-3.8-flash	0,375	0,0375	tidak tercantum	10%	tidak tercantum

Dua kolom persentase adalah hasil pembagian kami sendiri atas harga yang tercantum.

Sumber, semuanya diamati pada 2026-10-03:

• claude-sonnet-5 (halaman model: /models/claude-5/claude-sonnet-5)
• claude-sonnet-5-5 (halaman model: /models/claude-5/claude-sonnet-5-5)
• gpt-5.5 (halaman model: /models/gpt-5-5/gpt-5.5)
• deepseek-v4.1-flash (halaman model: /models/deepseek-v4/deepseek-v4.1-flash)
• gemini-3.8-flash (halaman model: /models/gemini-3/gemini-3.8-flash)

Tiga detail penting saat Anda membaca tabel ini.

Pertama, gpt-5.5 dan gemini-3.8-flash mencantumkan harga cache read tetapi tidak ada harga cache write. Kami tidak dapat memastikan dari data ini bagaimana prefiks pertama kali ditagih pada kedua model tersebut. Bukti tidak menyatakan bahwa itu gratis, dan tidak menyatakan bahwa itu ditagih dengan tarif input. Periksa Usage setelah permintaan pertama sebelum Anda membuat perkiraan berdasarkan asumsi apa pun.

Kedua, saat kami membaca deepseek-v4.1-flash, kami menemukan dua entri harga. Entri off-peak (selector offPeak: true) dan entri peak (offPeak: false) berbeda dua kali lipat di setiap baris. Penghematan cache per token Anda adalah persentase yang sama, tetapi nilai dolar absolut berlipat ganda saat peak.

Ketiga, ini adalah harga publik TokenLab. Panduan penagihan (diamati 2026-10-03) menyatakan bahwa permintaan yang selesai dikenakan biaya satu kali untuk opsi pengiriman yang menghasilkannya. Official mengikuti harga publik pembuat model, jadi pastikan opsi mana yang melayani permintaan Anda sebelum membandingkannya dengan lembar harga pembuat model.

Referensi Get a Model menunjukkan gpt-5.6-terra dengan prompt-cache di antara kapabilitasnya. Contoh responsnya tidak memuat harga, jadi kami tidak memasukkan model tersebut ke dalam tabel. Kami tidak memeriksa model lain dalam katalog.

Contoh perhitungan biaya prompt caching: satu system prompt panjang

Berikut skenarionya, dengan setiap input dinyatakan agar Anda dapat menukar dengan angka Anda sendiri. Ini adalah asumsi kami, bukan pengukuran.

• System prompt dan blok alat 20.000 token, identik pada setiap permintaan.
• Pesan pengguna 200 token yang berubah pada setiap permintaan.
• 1.000 permintaan, dengan cache tetap aktif selama seluruh proses, sehingga ada satu penulisan dan 999 pembacaan.
• Token output diabaikan, karena harganya sama dengan atau tanpa caching.

claude-sonnet-5 dengan input 0,90, read 0,09, dan write 1,125 per 1 juta token:

• Tanpa caching: 1.000 × 20.200 = 20.200.000 token × $0,90/1M = $18,18
• Cache write: 20.000 × $1,125/1M = $0,0225
• Cache reads: 999 × 20.000 = 19.980.000 × $0,09/1M = $1,7982
• Suffix tanpa cache: 1.000 × 200 = 200.000 × $0,90/1M = $0,18
• Dengan caching: 0,0225 + 1,7982 + 0,18 = sekitar $2,00, kira-kira 89% di bawah angka tanpa cache

Sekarang kasus kegagalan, dengan prefiks berubah sedikit pada setiap panggilan sehingga setiap permintaan membayar penulisan dan tidak pernah membaca. Itu memakan biaya 1.000 × 20.000 × $1,125/1M = $22,50 untuk prefiks, ditambah $0,18 yang sama untuk suffix. Totalnya adalah sekitar $22,68, yang mana $4,50 (25%) di atas $18,18 tanpa cache.

Titik impas mengikuti harga yang sama. Per 1 juta token prefiks, penulisan memakan biaya $0,225 lebih banyak daripada input biasa, dan setiap pembacaan menghemat $0,81. Satu hit mengganti biaya penulisan dengan sisa yang cukup (0,225 ÷ 0,81 ≈ 0,28 pembacaan per penulisan).

Skenario yang sama pada model lain:

Model	Tanpa cache	Dengan cache (estimasi)	Asumsi untuk permintaan pertama
claude-sonnet-5	$18,18	$2,00	harga write tercantum
claude-sonnet-5-5	$12,12	$1,33	harga write tercantum
deepseek-v4.1-flash off-peak	$3,03	$0,09	harga write tercantum
deepseek-v4.1-flash peak	$6,06	$0,19	harga write tercantum
gpt-5.5	$30,30	$3,33	tidak ada harga write; kami menagih 20.000 token dengan tarif input
gemini-3.8-flash	$7,58	$0,83	tidak ada harga write; kami menagih 20.000 token dengan tarif input

Untuk gpt-5.5, perhitungannya adalah 20.000 × $1,50/1M = $0,03, ditambah 19.980.000 × $0,15/1M = $2,997, ditambah 200.000 × $1,50/1M = $0,30. Dua baris yang ditandai didasarkan pada asumsi yang tidak didukung oleh bukti, jadi perlakukan sebagai angka kasar.

Membuat prompt dapat di-cache: apa yang dikonfirmasi oleh dokumentasi

Bukti mendukung daftar persyaratan singkat.

1. Pilih model yang mencantumkan prompt-cache. Array capabilities dari Get a Model (diamati 2026-10-03) adalah acuannya. Model tanpa kapabilitas ini tidak memberi Anda dasar untuk mengharapkan diskon.
2. Simpan konten bersama di posisi yang stabil. Pada endpoint Messages, system adalah field tingkat atas dan menerima string atau array blok konten. Pada Chat Completions, instruksi sistem masuk ke dalam messages. Bagaimanapun, materi yang diulang harus diletakkan di awal.
3. Kirim byte identik hingga batasnya. Ini adalah aturan prefiks-tepat dari versi asli artikel ini, dan cocok dengan cara kerja harga tabel. Harga baca hanya berlaku untuk bagian prompt yang cocok.

Request A: [ System Prompt + Tool Definitions ] [ User Query A ]
           ▲───────────── CACHED PREFIX ────────▲ ▲── SUFFIX ──▲

Request B: [ System Prompt + Tool Definitions ] [ User Query B ]
           ▲─────────── CACHE HIT (READ) ───────▲ ▲── SUFFIX ──▲

Tiga kebiasaan yang paling sering merusak penggunaan kembali:

• Stempel waktu, ID pengguna, atau ID sesi di bagian atas system prompt.
• Definisi alat atau kunci JSON yang diurutkan ulang antar permintaan.
• Perubahan indentasi atau baris baru dalam teks bersama.

Bentuk permintaan yang didokumentasikan oleh referensi Create Message:

{
  "model": "claude-sonnet-5",
  "max_tokens": 512,
  "system": [
    {
      "type": "text",
      "text": "You are a support assistant. The following policy governs all responses: [Full Policy Text]"
    }
  ],
  "messages": [
    { "role": "user", "content": "What is the return period for damaged items?" }
  ]
}

Draf awal artikel ini menempatkan penanda cache_control tipe ephemeral pada blok sistem tersebut. Referensi Create Message yang kami baca pada 2026-10-03 tidak mencantumkan field tersebut, jadi kami menghapusnya dari contoh. Hal yang sama berlaku untuk panjang prefiks minimum dan masa pakai cache. Kami tidak menemukan angka untuk keduanya dalam dokumentasi TokenLab yang kami baca. Sebelum mengandalkan penanda eksplisit atau TTL, uji model pilihan Anda dan bandingkan jumlah token yang di-cache di dua panggilan yang identik.

Membaca harga cache dan mengonfirmasi token yang di-cache

Jangan salin tabel di atas ke dalam kode. Panduan penagihan menyatakan untuk membaca harga saat ini saat aplikasi Anda membutuhkannya. Dua rute yang didokumentasikan:

curl "https://api.tokenlab.sh/v1/models/claude-sonnet-5"
curl "https://api.tokenlab.sh/v1/pricing?provider=openai&tag=chat"

Yang pertama mengembalikan kapabilitas, batas, dan harga satu model. ID model yang tidak dikenal mengembalikan 404 model_not_found. Yang kedua adalah endpoint publik yang tidak memerlukan API key. Contoh responsnya yang didokumentasikan menunjukkan input_per_1m_tokens dan output_per_1m_tokens untuk gpt-4o dan tidak ada field cache. updated_at dalam contoh tersebut adalah 2026-04-20, yang merupakan data contoh, bukan harga saat ini. Untuk harga cache, kami menggunakan endpoint per-model.

Untuk mengonfirmasi bahwa caching berhasil, objek usage yang didokumentasikan lebih tipis dari yang Anda harapkan. Chat Completions mencantumkan prompt_tokens, completion_tokens, dan total_tokens. Messages mencantumkan input_tokens dan output_tokens. Tidak ada referensi yang menyebutkan field token yang di-cache. Panduan biaya agen pengkodean (diamati 2026-10-03) menyatakan untuk mengonfirmasi penggunaan token yang di-cache dalam respons atau dalam Usage, dan untuk mencatat input, output, dan token yang di-cache per tugas.

Pengujian yang akan kami jalankan:

1. Kirim permintaan prefiks panjang yang sama dua kali, dengan jeda beberapa detik, hanya dengan pesan pengguna terakhir yang diubah.
2. Catat objek usage mentah lengkap dari kedua respons, ditambah billing_transaction_id jika ada.
3. Bandingkan biaya permintaan kedua di Usage dengan perhitungan di atas. Cache hit seharusnya berada di dekat angka "dengan cache", bukan angka tanpa cache.
4. Ulangi dengan baris pertama yang sengaja diubah untuk melihat biaya miss.

Untuk streaming Chat Completions, atur stream_options.include_usage: true untuk menerima penggunaan dalam potongan stream. Header penagihan bisa saja tidak ada pada stream, jadi gunakan Usage untuk biaya akhir. Panduan pemecahan masalah juga menjelaskan GET /v1/management/api-keys/{keyId}/usage, yang memfilter berdasarkan model, startDate, dan endDate untuk rekonsiliasi sisi server.

Kapan biaya prompt caching tidak sepadan

Caching adalah taruhan pada lalu lintas berulang. Caching merugi dalam situasi berikut:

• Prefiks tidak pernah berulang. Dokumen 20.000 token sekali pakai akan membayar premi penulisan apa pun dan tidak mendapatkan hasil apa pun.
• Permintaan datang terlalu lambat. Jika jeda antara permintaan yang cocok melebihi masa pakai cache, setiap panggilan adalah penulisan baru. Kami tidak menemukan masa pakai tersebut dalam bukti, jadi ukur jeda Anda sendiri terhadap apa yang dinyatakan halaman model.
• Prefiks berubah sebelum batasnya. Pengeluaran berlebih 25% dalam kasus kegagalan di atas berasal dari pola ini.
• Prefiks kecil. Penghematan berskala dengan token prefiks. Beberapa ratus token menghemat sebagian kecil sen per panggilan, dan ukuran minimum yang dapat di-cache tidak ada dalam bukti.
• Output mendominasi tagihan. Caching hanya memangkas input. Jika jawaban panjang, baris cache hanya menggeser sebagian kecil dari total.
• Model tidak mencantumkan harga cache. Panduan penagihan menyatakan bahwa tanda hubung di kolom harga TokenLab berarti tidak ada penawaran Verified, bukan gratis. Periksa detail harga model sebelum mengandalkan diskon apa pun.

Pola beban kerja	Kelayakan Caching	Mengapa
Loop alat multi-turn	Tinggi	Instruksi dan definisi alat tetap diperbaiki di seluruh langkah.
Banyak pengguna meminta satu dokumen besar	Tinggi	Lonjakan lalu lintas dengan cepat mengamortisasi penulisan.
Pekerjaan latar belakang yang jarang	Rendah	Jeda yang lebih lebar dari masa pakai cache memaksa penulisan berulang.
System prompt yang bervariasi	Rendah	Perubahan sebelum batas memutus kecocokan.

Prompt caching juga berbeda dari tip "Implement caching" dalam panduan penagihan, yang berarti menyimpan respons untuk permintaan identik yang berulang di aplikasi Anda sendiri. Itu menghindari panggilan model sepenuhnya, tetapi hanya membantu ketika seluruh permintaan berulang. Untuk sesi agen yang panjang, panduan biaya agen pengkodean mencakup ukuran konteks, batas output, dan pilihan model di samping caching.

FAQ

Apakah cache hit selalu membuat permintaan lebih murah?

Hanya untuk prefiks yang cocok, dan hanya jika model mencantumkan harga cache read. Pada model yang kami periksa, pembacaan memakan biaya 2% hingga 10% dari input. Suffix dan semua token output ditagih dengan tarif normal. Miss pada model dengan premi penulisan bisa memakan biaya lebih mahal daripada panggilan tanpa cache.

Apakah harga cache write yang hilang sama dengan gratis?

Tidak. Untuk gpt-5.5 dan gemini-3.8-flash, API langsung mencantumkan harga cache read dan tidak ada harga write pada 2026-10-03. Jalankan satu permintaan pertama dan baca biayanya di Usage daripada berasumsi nol atau tarif input.

Ke mana nilai per-pengguna masuk dalam prompt yang dapat di-cache?

Letakkan setelah konten bersama, dalam pesan pengguna atau entri messages terakhir. Apa pun yang bervariasi sebelum blok bersama akan mengubah prefiks dan memaksa penulisan baru. Itu termasuk stempel waktu, ID sesi, dan daftar alat yang diurutkan ulang.

Mengapa permintaan berulang menunjukkan tidak ada token yang di-cache?

Kami akan memeriksa empat hal secara berurutan. Apakah model mencantumkan prompt-cache? Apakah prefiks identik byte antar panggilan? Apakah panggilan kedua tiba di dalam masa pakai cache? Apakah jumlah yang di-cache berada di field yang dihapus oleh logging Anda? Dokumentasi yang kami baca tidak menyebutkan field tersebut, jadi catat seluruh objek usage.

Bandingkan harga cache langsung sebelum Anda berkomitmen pada model di halaman Model TokenLab.