Interactions API

Interactions API adalah cara terbaik untuk membangun aplikasi dengan model dan agen Gemini. Mulai Juni 2026, fitur ini Tersedia Secara Umum dan direkomendasikan untuk semua project baru. Meskipun kini dianggap sebagai API lama, API generateContent asli tetap didukung sepenuhnya.

Mengapa menggunakan Interactions API?

  • Antarmuka universal untuk semua aplikasi: Dirancang sebagai antarmuka standar untuk setiap kasus penggunaan, termasuk pembuatan teks satu giliran, pemahaman multimodal, output terstruktur, orkestrasi alat, dan alur kerja agentik.
  • Satu API untuk model dan agen: Satu endpoint dan pola terpadu untuk memanggil model Gemini standar serta agen khusus secara langsung (seperti Deep Research dan agen yang dikelola kustom).
  • Kemampuan baru yang siap digunakan: Fitur seperti status percakapan sisi server opsional menggunakan previous_interaction_id, langkah-langkah eksekusi yang dapat diamati untuk proses debug dan rendering UI, serta eksekusi di latar belakang untuk tugas yang berjalan lama menggunakan background=true.
  • Biaya lebih rendah dengan rasio hit cache yang lebih tinggi: Saat menggunakan percakapan multi-turn, pengelolaan status sisi server opsional memungkinkan penyiapan cache konteks yang lebih efisien di seluruh turn, sehingga mengurangi biaya token.
  • Tempat peluncuran fitur baru: Ke depannya, semua model baru, kemampuan multimodal, alat, dan fitur agen akan diluncurkan di Interactions API.

Secara default, Interactions API menyimpan permintaan sehingga Anda dapat memanfaatkan fitur pengelolaan status sisi server dengan menggunakan previous_interaction_id. Anda dapat memilih untuk menggunakan perilaku tanpa status dengan menyetel store=false. Lihat bagian retensi data untuk mengetahui detailnya.

Mulai

  • Siapkan agen coding Anda: Hubungkan ke MCP Dokumen Gemini dan instal keterampilan gemini-interactions-api untuk memberi asisten Anda akses langsung ke dokumentasi developer dan praktik terbaik terbaru. Untuk mengetahui langkah-langkah mendetail, lihat Panduan menyiapkan agen coding Anda
  • Bermigrasi dari generateContent: Jika Anda memiliki integrasi yang sudah ada, ikuti Panduan migrasi untuk beralih ke Interactions API.
  • Mulai: Ikuti langkah-langkah dalam panduan Memulai Interactions API.

Panduan fitur

Pelajari kemampuan spesifik Interactions API melalui panduan ini. Anda dapat menggunakan tombol di halaman ini untuk beralih antara generateContent dan Interactions API:

Cara kerja Interactions API

Interactions API berpusat pada resource inti: Interaction. Interaction mewakili giliran yang lengkap dalam percakapan atau tugas. Objek ini berfungsi sebagai catatan sesi, yang berisi seluruh histori interaksi sebagai urutan langkah-langkah eksekusi secara kronologis. Langkah-langkah ini mencakup pemikiran model, panggilan dan hasil alat sisi server atau sisi klien (seperti function_call dan function_result), serta model_output akhir. Resource yang disimpan (diambil melalui interactions.get) juga mencakup langkah-langkah user_input untuk konteks lengkap, meskipun respons interactions.create hanya menampilkan langkah-langkah yang dihasilkan model.

Saat melakukan panggilan ke interactions.create, Anda membuat resource Interaction baru.

Pengelolaan status sisi server

Anda dapat menggunakan id dari interaksi yang telah selesai dalam panggilan berikutnya menggunakan parameter previous_interaction_id untuk melanjutkan percakapan. Server menggunakan ID ini untuk mengambil histori percakapan, sehingga Anda tidak perlu mengirim ulang seluruh histori chat.

Parameter previous_interaction_id hanya mempertahankan histori percakapan (input dan output) menggunakan previous_interaction_id. Parameter lainnya adalah cakupan interaksi dan hanya berlaku untuk interaksi tertentu yang saat ini Anda buat:

  • tools
  • system_instruction
  • generation_config (termasuk thinking_level, temperature, dll.)

Artinya, Anda harus menentukan ulang parameter ini di setiap interaksi baru jika ingin menerapkannya. Pengelolaan status sisi server ini bersifat opsional; Anda juga dapat beroperasi dalam mode stateless dengan mengirimkan histori percakapan lengkap di setiap permintaan.

Penyimpanan dan retensi data

Secara default, API menyimpan semua objek Interaksi (store=true) untuk menyederhanakan penggunaan fitur pengelolaan status sisi server (dengan previous_interaction_id), eksekusi latar belakang (menggunakan background=true), dan tujuan kemampuan pengamatan.

  • Paket berbayar: Sistem menyimpan interaksi selama 55 hari.
  • Paket gratis: Sistem menyimpan interaksi selama 1 hari.

Jika tidak menginginkannya, Anda dapat menetapkan store=false dalam permintaan Anda. Kontrol ini terpisah dari pengelolaan status ; Anda dapat menonaktifkan penyimpanan untuk interaksi apa pun. Namun, perhatikan bahwa store=false tidak kompatibel dengan eksekusi di latar belakang dan mencegah penggunaan previous_interaction_id untuk giliran berikutnya.

Untuk project Tingkat Berbayar, Anda dapat mengonfigurasi periode retensi di AI Studio untuk otomatis menandai log agar dihapus dari penyimpanan project setelah 7, 14, 28, atau 55 hari. Retensi yang lebih pendek dapat memengaruhi pengambilan percakapan sebelumnya.

Anda dapat menghapus interaksi tersimpan kapan saja menggunakan metode delete secara terprogram, yang memerlukan ID interaksi. Anda juga dapat melihat dan mengelola log interaksi tersimpan, termasuk penghapusan dari penyimpanan project, di AI Studio.

Setelah periode retensi berakhir, data Anda akan dihapus secara otomatis.

Objek interaksi diproses sesuai dengan persyaratan.

Melihat interaksi di AI Studio

API menyimpan permintaan Interactions API yang dieksekusi dengan store=true untuk project di Tingkat Berbayar. Anda dapat melihatnya langsung dari halaman Logs di Google AI Studio. Lihat Panduan log untuk mengetahui informasi selengkapnya.

Praktik terbaik

  • Rasio hit cache: Cache implisit didukung dalam mode stateful dan stateless (lihat Panduan memulai). Penggunaan previous_interaction_id (berstatus) untuk melanjutkan percakapan memungkinkan sistem lebih mudah memanfaatkan caching implisit untuk histori percakapan, yang meningkatkan performa dan mengurangi biaya.
  • Mencampur interaksi: Anda memiliki fleksibilitas untuk mencampur dan mencocokkan interaksi Agen dan Model dalam percakapan. Misalnya, Anda dapat menggunakan agen khusus, seperti agen Deep Research, untuk pengumpulan data awal, lalu menggunakan model Gemini standar untuk tugas lanjutan seperti meringkas atau memformat ulang, dengan menautkan langkah-langkah ini dengan previous_interaction_id.

Model & agen yang didukung

Nama Model Jenis ID Model
Gemini 3.5 Flash Model gemini-3.5-flash
Pratinjau Gemini 3.1 Pro Model gemini-3.1-pro-preview
Gemini 3.1 Flash-Lite Model gemini-3.1-flash-lite
Pratinjau Gemini 3 Flash Model gemini-3-flash-preview
Gemini 2.5 Pro Model gemini-2.5-pro
Gemini 2.5 Flash Model gemini-2.5-flash
Gemini 2.5 Flash-lite Model gemini-2.5-flash-lite
Gemini 3 Pro Image Model gemini-3-pro-image
Gambar Gemini 3.1 Flash Model gemini-3.1-flash-image
Pratinjau Gemini 3.1 Flash TTS Model gemini-3.1-flash-tts-preview
Gemma 4 31B IT Model gemma-4-31b-it
Gemma 4 26B MoE IT Model gemma-4-26b-a4b-it
Pratinjau Klip Lyria 3 Model lyria-3-clip-preview
Pratinjau Lyria 3 Pro Model lyria-3-pro-preview
Pratinjau Deep Research Agen deep-research-preview-04-2026
Pratinjau Deep Research Agen deep-research-max-preview-04-2026
Pratinjau Antigravity Agen antigravity-preview-05-2026

SDK

Anda dapat menggunakan Google GenAI SDK versi terbaru untuk mengakses Interactions API.

  • Di Python, ini adalah paket google-genai dari versi 2.3.0 dan seterusnya.
  • Di JavaScript, ini adalah paket @google/genai dari versi 2.3.0 dan seterusnya.

Anda dapat mempelajari lebih lanjut cara menginstal SDK di halaman Libraries.

Batasan

  • MCP Jarak Jauh: Gemini 3 tidak mendukung MCP jarak jauh, fitur ini akan segera hadir.
  • Kompatibilitas model multi-giliran: Saat menggabungkan model yang berbeda dalam percakapan (baik yang memiliki status maupun tidak), model berikutnya harus mendukung modalitas output model sebelumnya sebagai input. Misalnya, jika Anda membuat gambar menggunakan gemini-3.1-flash-image, Anda tidak dapat melanjutkan percakapan tersebut dengan model yang tidak menerima input gambar (seperti model khusus teks atau model pembuatan musik seperti Lyria).

Fitur berikut didukung oleh API generateContent, tetapi belum tersedia di Interactions API:

Masukan

Masukan Anda sangat penting untuk pengembangan Interactions API. Sampaikan pendapat Anda, laporkan bug, atau minta fitur di Forum Komunitas Developer AI Google kami.

Langkah berikutnya