> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Panduan Penggunaan Cache Konteks Claude

> Simpan prefiks prompt yang digunakan berulang kali ke cache melalui API Claude Messages atau API Chat Completions yang kompatibel dengan OpenAI untuk mengurangi biaya token akibat pemrosesan berulang atas konten panjang.

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:

```bash theme={null}
export API_KEY="KUNCI_API_ANDA"
```

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

## 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:

```bash theme={null}
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."
      }
    ]
  }'
```

<Warning>`system` harus berupa array blok konten. `cache_control` tidak dapat ditambahkan jika `system` berupa string.</Warning>

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`:

```bash theme={null}
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`:

```json theme={null}
{
  "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:

```text theme={null}
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:

```bash theme={null}
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`:

```bash theme={null}
-H "anthropic-beta: extended-cache-ttl-2025-04-11"
```

```json theme={null}
"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.

```json theme={null}
{
  "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:

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

<Warning>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.</Warning>

### 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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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`                                                                          |

<Note>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.</Note>

<Note>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.</Note>

<Warning>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`.</Warning>

## 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`.

```bash theme={null}
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:

```text theme={null}
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?