Panduan Penggunaan Cache Konteks Gemini

Panduan ini menjelaskan cara membuat dan menggunakan kembali cache konteks Gemini (Context Cache) melalui API Chat Completions yang kompatibel dengan OpenAI atau API native Gemini. Sebelum memulai:

export API_KEY="KUNCI_API_ANDA"

Contoh dalam panduan ini menggunakan gemini-3.6-flash. Untuk mengetahui apakah model lain mendukung Context Cache, lihat deskripsi model dan halaman harga 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 sangat panjang
Basis pengetahuan tetap atau dokumentasi produk
Pesan riwayat yang stabil dalam percakapan multi-giliran
Definisi dan petunjuk tool yang digunakan berulang kali

Context Cache cocok untuk permintaan dengan “konten awal yang tetap sama dan hanya pertanyaan terakhir yang terus berubah”.

Penggunaan dasar

Tambahkan cache_control ke blok konten pada pesan terakhir dalam prefiks stabil:

{
  "type": "text",
  "text": "Ini adalah bagian konten terakhir dalam prefiks stabil",
  "cache_control": {
    "type": "ephemeral",
    "ttl": "5m"
  }
}

TTL yang didukung:

TTL	Arti
`5m`	Cache selama 5 menit
`1h`	Cache selama 1 jam

Jika ttl dihilangkan, nilai defaultnya adalah 5m.

Struktur pesan

Sebaiknya gunakan struktur berikut:

system
→ Teks panjang atau pesan riwayat yang stabil
→ Batas prefiks stabil dengan cache_control
→ Pertanyaan pengguna saat ini (tidak disimpan ke cache)

Pesan yang memuat cache_control dan semua pesan sebelumnya membentuk prefiks yang disimpan ke cache. Setidaknya harus ada satu pesan real-time setelahnya.

Contoh permintaan yang kompatibel dengan OpenAI

curl "https://api.apimart.ai/v1/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.6-flash",
    "stream": false,
    "messages": [
      {
        "role": "system",
        "content": "Jawab pertanyaan hanya berdasarkan materi referensi yang diberikan."
      },
      {
        "role": "user",
        "content": "Tempatkan materi referensi panjang yang akan digunakan berulang kali di sini…"
      },
      {
        "role": "assistant",
        "content": [
          {
            "type": "text",
            "text": "Saya telah membaca dan memahami materi referensi di atas.",
            "cache_control": {
              "type": "ephemeral",
              "ttl": "5m"
            }
          }
        ]
      },
      {
        "role": "user",
        "content": "Ringkas tiga poin utama dalam materi referensi tersebut."
      }
    ]
  }'

Saat permintaan dikirim untuk pertama kalinya, sistem akan mencoba membuat cache dan menggunakannya untuk menyelesaikan permintaan saat ini.

Anda tidak perlu memanggil endpoint terpisah untuk membuat cache. cache_control sekaligus menetapkan “batas cache” dan “masa berlaku cache”.

Contoh permintaan native Gemini

Endpoint native Gemini generateContent juga mendukung penambahan cache_control di dalam contents[].parts[]:

curl "https://api.apimart.ai/v1beta/models/gemini-3.6-flash:generateContent" \
  -H "x-goog-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "systemInstruction": {
      "parts": [
        {
          "text": "Jawab pertanyaan hanya berdasarkan materi referensi yang diberikan."
        }
      ]
    },
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "Tempatkan materi referensi panjang yang akan digunakan berulang kali di sini…"
          }
        ]
      },
      {
        "role": "model",
        "parts": [
          {
            "text": "Saya telah membaca dan memahami materi referensi di atas.",
            "cache_control": {
              "type": "ephemeral",
              "ttl": "5m"
            }
          }
        ]
      },
      {
        "role": "user",
        "parts": [
          {
            "text": "Ringkas tiga poin utama dalam materi referensi tersebut."
          }
        ]
      }
    ]
  }'

cache_control adalah kolom ekstensi platform dalam format permintaan Gemini. Setelah mengidentifikasi batas, platform menghapus kolom ini sebelum meneruskan permintaan, lalu secara otomatis membuat atau menggunakan kembali konten cache (cachedContent). Antarmuka streaming menggunakan isi permintaan yang sama; Anda hanya perlu mengubah alamat menjadi:

curl -N "https://api.apimart.ai/v1beta/models/gemini-3.6-flash:streamGenerateContent?alt=sse" \
  -H "x-goog-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "Tempatkan materi referensi panjang yang akan digunakan berulang kali di sini…",
            "cache_control": {
              "type": "ephemeral",
              "ttl": "5m"
            }
          }
        ]
      },
      {
        "role": "user",
        "parts": [
          {
            "text": "Ringkas tiga poin utama dalam materi referensi tersebut."
          }
        ]
      }
    ]
  }'

Saat menggunakan kembali cache, pertahankan systemInstruction, contents sebelum batas, TTL, dan tools tanpa perubahan; ubah hanya konten real-time setelah batas.

Alur pembuatan dan penggunaan kembali

Saat Anda mengirim permintaan dengan cache_control untuk pertama kalinya:

Identifikasi prefiks stabil
→ Buat Context Cache
→ Rujuk cache baru dalam permintaan saat ini
→ Kembalikan hasil model

Saat Anda mengirim kembali prefiks stabil yang sama:

Identifikasi prefiks stabil yang sama
→ Gunakan kembali Context Cache yang belum kedaluwarsa
→ Kirim hanya konten real-time saat ini
→ Kembalikan hasil model

Oleh karena itu, permintaan pertama juga dapat langsung mengembalikan token cache dalam jumlah besar. Ini adalah perilaku normal dan tidak mengharuskan Anda mengirim “permintaan pemanasan” terlebih dahulu.

Menggunakan kembali cache

Pada permintaan berikutnya, pertahankan hal-hal berikut tanpa perubahan:

Model
Semua pesan sebelum cache_control
cache_control.ttl
Definisi tool (jika menggunakan tools)
systemInstruction dalam permintaan native Gemini

Ubah hanya pertanyaan real-time setelah batas:

{
  "role": "user",
  "content": "Risiko apa saja yang disebutkan dalam materi referensi?"
}

Selama prefiks stabil tetap sama dan cache belum kedaluwarsa, sistem akan menggunakan kembali cache yang ada. Perubahan berikut akan menghasilkan cache yang berbeda:

Mengubah teks atau urutan pesan dalam prefiks stabil
Mengganti model
Mengubah 5m menjadi 1h
Mengubah tools atau definisi parameter tool
Menggunakan pengguna atau kanal API yang berbeda

Contoh Python

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apimart.ai/v1",
)

stable_messages = [
    {
        "role": "system",
        "content": "Jawab pertanyaan hanya berdasarkan materi referensi yang diberikan.",
    },
    {
        "role": "user",
        "content": "Tempatkan materi referensi panjang yang akan digunakan berulang kali di sini…",
    },
    {
        "role": "assistant",
        "content": [
            {
                "type": "text",
                "text": "Saya telah membaca dan memahami materi referensi di atas.",
                "cache_control": {
                    "type": "ephemeral",
                    "ttl": "5m",
                },
            }
        ],
    },
]

response = client.chat.completions.create(
    model="gemini-3.6-flash",
    messages=[
        *stable_messages,
        {
            "role": "user",
            "content": "Ringkas tiga poin utama dalam materi referensi tersebut.",
        },
    ],
)

print(response.choices[0].message.content)
print(response.usage)

Pada permintaan berikutnya, gunakan kembali stable_messages yang sama dan ganti hanya pesan user terakhir.

Memeriksa apakah cache digunakan

Respons yang kompatibel dengan OpenAI

Periksa kolom berikut dalam respons:

{
  "usage": {
    "prompt_tokens": 14430,
    "prompt_tokens_details": {
      "cached_tokens": 14420,
      "cache_write_tokens": 0
    }
  }
}

Keterangan kolom:

Kolom	Arti
`prompt_tokens`	Total token input untuk permintaan ini
`cached_tokens`	Token input yang dibaca dari cache untuk permintaan ini
`cache_write_tokens`	Token yang ditulis ke cache; nilai `0` adalah normal

Permintaan pertama juga dapat menampilkan nilai cached_tokens yang besar karena sistem dapat membuat cache, lalu merujuknya dalam panggilan model yang sama.

Respons native Gemini

Periksa usageMetadata.cachedContentTokenCount dalam respons:

{
  "usageMetadata": {
    "promptTokenCount": 13926,
    "cachedContentTokenCount": 13916,
    "totalTokenCount": 13954
  }
}

Keterangan kolom:

Kolom	Arti
`promptTokenCount`	Total token input untuk permintaan ini
`cachedContentTokenCount`	Token input yang dibaca dari cache untuk permintaan ini
`totalTokenCount`	Total token input dan output untuk permintaan ini

streamGenerateContent mengembalikan usageMetadata yang sama dalam frame respons SSE. Klien harus membaca frame yang memuat kolom tersebut, bukan hanya memeriksa potongan teks pertama.

Rekomendasi penggunaan

Simpan ke cache hanya konten panjang yang benar-benar stabil dan akan digunakan kembali beberapa kali.
Tempatkan pertanyaan yang berubah pada setiap permintaan setelah batas cache_control.
Jangan sertakan timestamp, ID acak, atau informasi pengguna yang dinamis dalam prefiks stabil.
Gunakan 5m jika Anda memperkirakan panggilan akan diulang dalam waktu singkat.
Gunakan 1h jika Anda memerlukan jangka waktu penggunaan kembali yang lebih panjang.
Jika prefiks terlalu pendek, model tidak mendukung cache, atau cache sedang tidak tersedia, permintaan dapat diproses secara otomatis dengan cara biasa.
Dalam format native Gemini, batas cache harus ditempatkan di contents[].parts[], bukan di systemInstruction.

Pertanyaan umum

Apakah format permintaan native Gemini dapat membuat cache secara otomatis?

Ya. generateContent dan streamGenerateContent menggunakan struktur cache_control yang sama. Batas harus ditempatkan di contents[].parts[], dan setidaknya harus ada satu content real-time setelah content yang memuat batas.Jika permintaan sudah secara eksplisit menyediakan nama resource cachedContent native, platform akan memprioritaskan resource yang diberikan pengguna dan tidak lagi membuat cache secara otomatis.

Mengapa cache tidak digunakan?

Penyebab yang umum meliputi:

Prefiks stabil tidak sama persis dengan permintaan sebelumnya
TTL telah kedaluwarsa
Model atau tools telah diubah
Konten cache tidak mencapai jumlah minimum token yang diwajibkan oleh model
cache_control ditempatkan pada pesan terakhir sehingga tidak ada pertanyaan real-time yang tersisa

Apakah cache_control dapat ditempatkan pada pesan terakhir?

Tidak disarankan. Pesan terakhir biasanya merupakan pertanyaan real-time saat ini dan tidak seharusnya disimpan ke cache. Jika tidak ada pesan real-time setelah batas, permintaan akan diproses dengan cara biasa.

Apakah saya dapat menetapkan TTL lain?

Tidak. Saat ini hanya 5m dan 1h yang didukung. Nilai lain akan menghasilkan error HTTP 400.

Apakah saya dapat menetapkan beberapa batas cache?

Ya, tetapi semua batas harus menggunakan TTL yang sama dan sistem akan menggunakan batas terakhir. Secara umum, sebaiknya tetapkan hanya satu batas per permintaan agar strukturnya lebih jelas.

Apakah permintaan akan gagal jika cache tidak tersedia?

Biasanya tidak. Jika syarat untuk membuat atau menggunakan kembali cache tidak terpenuhi, sistem akan memproses permintaan secara otomatis dengan cara biasa. Pengecualiannya adalah error parameter, seperti TTL yang tidak valid atau penggunaan beberapa TTL yang berbeda.

Apa yang terjadi jika Context Cache tidak diaktifkan untuk model?

Permintaan akan diproses secara otomatis dengan cara biasa tanpa membuat cache eksplisit atau menimbulkan biaya penyimpanan cache. Input dan output biasa, serta kemungkinan hit pada cache implisit, akan tetap ditagih berdasarkan aturan model yang berlaku.

Mengapa cache_write_tokens bernilai 0?

Ini adalah perilaku normal cache konteks Gemini. Biaya pembuatan dicatat sebagai biaya penyimpanan cache tersendiri; cache_write_tokens dengan gaya OpenAI atau Claude tidak digunakan untuk menunjukkan jumlah token yang ditulis ke cache.

Apakah cached_tokens yang lebih besar dari 0 berarti cache eksplisit pasti telah dibuat?

Belum tentu. Sistem juga dapat menghasilkan hit pada cache implisit. Bagi pengguna biasa, token yang dibaca dari cache dapat digunakan untuk menentukan apakah permintaan memperoleh manfaat dari pembacaan cache. Jika Anda perlu memeriksa biaya pembuatan cache eksplisit, lihat catatan penggunaan Context Cache storage di platform.

Bagaimana biaya cache dihitung?

Saat cache dibuat, biaya penyimpanan cache satu kali mungkin dikenakan. Saat cache digunakan, token yang cocok dikenai harga pembacaan cache. Untuk harga spesifik, lihat halaman harga model di platform.

Ikhtisar

Seri Teks

Seri Gambar

Seri Video

Seri Audio

Seri Moderasi

Manajemen Unggahan

Manajemen Tugas

Manajemen Akun

Panduan Penggunaan Cache Konteks Gemini

Kasus penggunaan

Penggunaan dasar

Struktur pesan

Contoh permintaan yang kompatibel dengan OpenAI

Contoh permintaan native Gemini

Alur pembuatan dan penggunaan kembali

Menggunakan kembali cache

Contoh Python

Memeriksa apakah cache digunakan

Respons yang kompatibel dengan OpenAI

Respons native Gemini

Rekomendasi penggunaan

Pertanyaan umum

​Kasus penggunaan

​Penggunaan dasar

​Struktur pesan

​Contoh permintaan yang kompatibel dengan OpenAI

​Contoh permintaan native Gemini

​Alur pembuatan dan penggunaan kembali

​Menggunakan kembali cache

​Contoh Python

​Memeriksa apakah cache digunakan

​Respons yang kompatibel dengan OpenAI

​Respons native Gemini

​Rekomendasi penggunaan

​Pertanyaan umum

Kasus penggunaan

Penggunaan dasar

Struktur pesan

Contoh permintaan yang kompatibel dengan OpenAI

Contoh permintaan native Gemini

Alur pembuatan dan penggunaan kembali

Menggunakan kembali cache

Contoh Python

Memeriksa apakah cache digunakan

Respons yang kompatibel dengan OpenAI

Respons native Gemini

Rekomendasi penggunaan

Pertanyaan umum