Interactions API

Interactions API adalah antarmuka baru kami dan cara paling mudah untuk membangun dengan model dan agen Gemini. Mulai Juni 2026, API ini tersedia secara Umum dan merupakan antarmuka yang direkomendasikan untuk semua project baru.

Meskipun kini dianggap sebagai API lama, API asli tetap didukung sepenuhnya.generateContent

Mengapa menggunakan Interactions API?

  • Kemampuan baru yang siap digunakan: Status percakapan sisi server opsional menggunakan previous_interaction_id, langkah eksekusi yang dapat diamati untuk proses debug dan rendering UI, serta eksekusi latar belakang untuk tugas yang berjalan lama menggunakan background=true.
  • Biaya lebih rendah dengan rasio hit cache yang lebih tinggi: Pengelolaan status sisi server memungkinkan caching konteks yang lebih efisien di seluruh giliran, sehingga mengurangi biaya token untuk percakapan multi-giliran.
  • Dibuat untuk model dan agen canggih: Dibuat khusus untuk model penalaran , penggunaan alat multi-langkah, dan alur penalaran yang kompleks, sehingga menyederhanakan proses pembuatan, proses debug, dan orkestrasi aplikasi agentic.
  • Satu API untuk model dan agen: Satu antarmuka terpadu untuk memanggil model dan agen Gemini secara langsung seperti Deep Research dan agen terkelola kustom, tanpa endpoint atau pola terpisah yang perlu dipelajari.
  • Tempat peluncuran fitur baru: Ke depannya, model dan kemampuan baru di luar keluarga utama, bersama dengan kemampuan dan alat agentic baru akan diluncurkan di Interactions API.

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

Mulai

  • Menyiapkan agen coding: Hubungkan ke MCP Dokumen Gemini dan instal keterampilan gemini-interactions-api untuk memberi asisten Anda akses langsung ke dokumen developer dan praktik terbaik terbaru. Menyiapkan agen coding →
  • Bermigrasi dari generateContent: Jika Anda memiliki integrasi yang ada, ikuti Panduan Migrasi untuk bertransisi ke Interactions API.
  • Mulai: Mulai di Interactions API Panduan memulai.

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 lengkap dalam percakapan atau tugas. Tindakan ini berfungsi sebagai catatan sesi, yang berisi seluruh histori interaksi sebagai urutan kronologis langkah eksekusi. 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 tersimpan (diambil melalui interactions.get) juga mencakup langkah user_input untuk konteks lengkap, meskipun respons interactions.create hanya menampilkan langkah yang dihasilkan model.

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

Pengelolaan status sisi server

Anda dapat menggunakan id interaksi yang telah selesai dalam panggilan berikutnya menggunakan previous_interaction_id parameter 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 bercakupan 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 kembali parameter ini di setiap interaksi baru jika ingin menerapkannya. Pengelolaan status sisi server ini bersifat opsional. Anda juga dapat beroperasi dalam mode tanpa status 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 observabilitas.

  • 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. Kontrol ini terpisah dari pengelolaan status. Anda dapat memilih untuk tidak menyimpan interaksi apa pun. Namun, perhatikan bahwa store=false tidak kompatibel dengan background=true dan mencegah penggunaan previous_interaction_id untuk giliran berikutnya.

Anda dapat menghapus interaksi tersimpan kapan saja menggunakan metode penghapusan yang ditemukan di Referensi API. Anda hanya dapat menghapus interaksi jika mengetahui ID interaksi.

Setelah periode retensi berakhir, data Anda akan otomatis dihapus.

Sistem memproses objek Interaksi sesuai dengan persyaratan.

Praktik terbaik

  • Rasio hit cache: Menggunakan previous_interaction_id 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
Gemini 3.1 Flash Image 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 yang lebih baru.
  • Di JavaScript, ini adalah paket @google/genai dari versi 2.3.0 dan yang lebih baru.

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

Batasan

  • MCP jarak jauh: Gemini 3 tidak mendukung MCP jarak jauh, tetapi fitur ini akan segera hadir.

Fitur berikut didukung oleh generateContent API, 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