> ## 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 Cache Konteks OpenAI

> Gunakan cache 30 menit atau 12 jam melalui Responses API untuk menggunakan kembali prompt, dokumen, dan prefiks percakapan yang tetap.

Untuk model GPT-5.6 dan yang lebih baru yang mendukung fitur ini, atur `prompt_cache_options.ttl` dalam permintaan [Responses API](https://docs.apimart.ai/id/api-reference/texts/openai/responses.md) untuk memilih masa cache minimum 30 menit atau 12 jam. Contoh menggunakan `gpt-6.1-terra`.

> [!NOTE]
>
> Cache 12 jam hanya didukung oleh `/v1/responses`, bukan `/v1/chat/completions`. TTL menentukan masa minimum, bukan batas waktu penghapusan atau jaminan bahwa setiap permintaan menggunakan cache.

## Atur kunci API

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

> [!NOTE]
>
> Teks panjang dalam contoh adalah teks pengganti. Ganti dengan konten yang ingin digunakan kembali. Prefiks yang akan disimpan harus berisi minimal 1.024 token; teks pengganti pendek ini saja tidak memicu penulisan cache.

## Menggunakan cache 30 menit

Atur `prompt_cache_options.ttl` ke `"30m"`. Jika `ttl` dihilangkan, nilainya juga 30 menit. Jika `mode` dihilangkan, cache implisit digunakan dan layanan hulu memilih titik batas cache secara otomatis.

```bash theme={null}
curl "https://api.apimart.ai/v1/responses" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-6.1-terra",
  "prompt_cache_options": {
    "ttl": "30m"
  },
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Long reference material to reuse (at least 1024 tokens)... Summarize the key points."
        }
      ]
    }
  ]
}'
```

## Menggunakan cache 12 jam

Ubah kolom yang sama menjadi `"12h"` dan pertahankan struktur permintaan lainnya:

```bash theme={null}
curl "https://api.apimart.ai/v1/responses" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-6.1-terra",
  "prompt_cache_options": {
    "ttl": "12h"
  },
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Long reference material to reuse (at least 1024 tokens)... Summarize the key points."
        }
      ]
    }
  ]
}'
```

## Menggunakan prefiks tetap untuk pertanyaan berbeda

Untuk menggunakan kembali dokumen panjang sambil mengubah hanya pertanyaan terakhir, atur `mode` ke `"explicit"` dan tambahkan `prompt_cache_breakpoint` pada blok `input_text` di akhir konten tetap. Contoh ini menggunakan 12 jam; untuk 30 menit, ubah TTL permintaan menjadi `"30m"`.

> [!NOTE]
>
> Mengatur `mode: "explicit"` tanpa titik batas menonaktifkan pembacaan dan penulisan cache. Titik batas di bawah tidak memiliki TTL tersendiri, sehingga mewarisi `prompt_cache_options.ttl` dari permintaan.

```bash theme={null}
curl "https://api.apimart.ai/v1/responses" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-6.1-terra",
  "prompt_cache_options": {
    "ttl": "12h",
    "mode": "explicit"
  },
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Long reference material to reuse (at least 1024 tokens)...",
          "prompt_cache_breakpoint": {
            "mode": "explicit"
          }
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Summarize the three main points in the reference material."
        }
      ]
    }
  ]
}'
```

Kirim model, prefiks tetap, dan titik batas yang sama pada permintaan berikutnya. Ubah hanya pesan pengguna terakhir. Pertahankan konten, urutan, dan pengaturan yang memengaruhi konteks. Anda tidak perlu membuat atau mengirim ID cache.

## Memeriksa penggunaan cache

Periksa `usage.input_tokens_details` dalam respons:

* `cached_tokens`: Token yang dibaca dari cache dalam permintaan ini. Nilai di atas 0 menunjukkan pembacaan cache.
* `cache_write_tokens`: Total token yang ditulis ke cache dalam permintaan ini.
* `cache_write_tokens_details.ttl_30m_tokens`: Token yang ditulis dengan TTL 30 menit dalam permintaan ini.
* `cache_write_tokens_details.ttl_12h_tokens`: Token yang ditulis dengan TTL 12 jam dalam permintaan ini.

Setelah penulisan pertama, kirim permintaan lagi dengan prefiks tetap yang sama dan periksa `cached_tokens`. Nilainya bisa 0 jika prefiks terlalu pendek, konten berubah, atau cache tidak cocok.

### Contoh cache usage dan penghitungan token

Cuplikan respons ini hanya menampilkan `usage` untuk model OpenAI yang mendukung cache, dengan penulisan pada kedua TTL. Nilai aktual mengikuti respons.

```json theme={null}
{
  "usage": {
    "input_tokens": 12000,
    "input_tokens_details": {
      "cached_tokens": 4000,
      "cache_write_tokens": 7000,
      "cache_write_tokens_details": {
        "ttl_30m_tokens": 5000,
        "ttl_12h_tokens": 2000
      }
    },
    "output_tokens": 1000,
    "total_tokens": 13000
  }
}
```

Token masukan biasa:

```text theme={null}
input_tokens - input_tokens_details.cached_tokens - input_tokens_details.cache_write_tokens
```

```text theme={null}
cache_write_tokens = ttl_30m_tokens + ttl_12h_tokens
total_tokens = input_tokens + output_tokens
```

Pembacaan dan penulisan cache sudah termasuk dalam `input_tokens`. Kedua hitungan TTL adalah bagian dari `cache_write_tokens`: jangan menjumlahkan kembali total dan rinciannya, atau menambahkan pembacaan dan penulisan cache ke total masukan.

Di sini, masukan biasa adalah `12000 - 4000 - 7000 = 1000`, penulisan adalah `5000 + 2000 = 7000`, dan total token adalah `12000 + 1000 = 13000`.

Lihat [panduan resmi cache prompt OpenAI](https://developers.openai.com/api/docs/guides/prompt-caching) untuk perilaku cache.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.