Interactions API

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

Mengapa menggunakan Interactions API?

  • Antarmuka universal untuk semua aplikasi: Didesain sebagai antarmuka standar untuk setiap kasus penggunaan, termasuk pembuatan teks satu putaran, pemahaman multimodal, output terstruktur, orkestrasi alat, dan alur kerja agen.
  • 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 terkelola kustom).
  • Kemampuan baru yang siap digunakan: Fitur seperti 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: Saat menggunakan percakapan multi-putaran, pengelolaan status sisi server opsional memungkinkan caching konteks yang lebih efisien di seluruh putaran, sehingga mengurangi biaya token.
  • Tempat peluncuran fitur baru: Ke depannya, semua model, kemampuan multimodal, alat, dan fitur agen 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 Gemini Docs MCP 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 beralih ke Interactions API.
  • Mulai: Mulai di 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 putaran 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 yang disimpan (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 observasi.

  • 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 eksekusi latar belakang dan mencegah penggunaan previous_interaction_id untuk putaran berikutnya.

Untuk project Paket 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 singkat dapat memengaruhi pengambilan percakapan sebelumnya.

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

Setelah periode retensi berakhir, data Anda akan otomatis dihapus.

Objek interaksi diproses sesuai dengan persyaratan.

Melihat Interaksi di AI Studio

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

Praktik terbaik

  • Rasio hit cache: Caching implisit didukung dalam mode stateful dan stateless (lihat Panduan memulai). Menggunakan previous_interaction_id (stateful) 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, fitur ini akan segera hadir.
  • Kompatibilitas model multi-putaran: Saat mencampur model yang berbeda dalam percakapan (stateful atau stateless), 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 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