Gemini Interactions API vs generateContent: Mana yang Dipilih? 4 Tabel Menjelaskan Perbandingan Terbaru 2026

打开 Gemini 官方文档，尤其是 Nano Banana 图片生成这类页面，你可能会注意到页面顶部多了一个切换开关——一边是 Interactions API，一边是 generateContent API。Ini bukan sekadar perubahan tampilan dokumentasi, melainkan Google pada Juni 2026 resmi mendorong Interactions API ke posisi GA (siap pakai secara resmi), dan merekomendasikan semua proyek baru untuk memprioritaskannya. Artikel ini menggabungkan dokumentasi resmi dan hasil uji di gateway APIYI untuk menjelaskan perbedaan inti, celah kemampuan, dan saran pemakaian praktis keduanya sekaligus.

Nilai inti: Setelah membaca artikel ini, kamu akan paham perbedaan Interactions API dan generateContent dalam hal filosofi desain, manajemen status, dan cakupan kemampuan, serta tahu范式 mana yang sebaiknya dipilih saat memanggil Gemini lewat layanan proksi APIYI.

Perbedaan inti Interactions API dan generateContent

Kesimpulannya dulu: kedua API ini bukan sekadar hubungan versi lama dan versi baru, melainkan dua filosofi desain yang berbeda. generateContent adalah mode tanpa status dengan pola “satu permintaan, satu respons”, sehingga klien harus mengelola sendiri riwayat percakapan lengkap; sedangkan Interactions API memindahkan manajemen status ke server dan merancang ulang seluruh alur interaksi di sekitar konsep baru bernama “Interaction”.

Dokumentasi resmi mendefinisikan satu Interaction sebagai “satu putaran percakapan atau tugas yang lengkap”, yang di dalamnya terdiri dari serangkaian langkah eksekusi yang tersusun secara kronologis, termasuk proses berpikir model, panggilan alat dan hasil yang dikembalikan, serta keluaran akhir model. Artinya, Interactions API sejak awal memang dirancang untuk percakapan multi-turn dan tugas bergaya agent, bukan hanya tanya jawab sekali jalan.

Ini juga menjelaskan kenapa Google memakai istilah “GA” alih-alih sekadar “fitur baru”. Interactions API masuk pratinjau publik pada Desember 2025, lalu diumumkan resmi GA pada Juni 2026. Blog resmi bahkan menuliskan: “Kami menyarankan semua proyek dan aplikasi baru menggunakan Interactions API”, sementara seluruh dokumentasi resmi kini secara default menampilkan paradigma baru ini. Google juga sedang mendorong SDK pihak ketiga dan mitra ekosistem untuk menjadikannya interface default. Dengan kata lain, ini bukan pembaruan opsional biasa, melainkan redefinisi Google tentang cara memanggil Gemini. Yang ada hanyalah panduan migrasi untuk membantu developer berpindah bertahap sesuai ritme masing-masing, bukan pemaksaan serentak.

Dimensi Perbandingan	generateContent (legacy)	Interactions API
Status saat ini	Legacy tapi tetap didukung penuh	GA resmi mulai Juni 2026
Rekomendasi resmi	Proyek yang sudah ada boleh lanjut	Disarankan untuk semua proyek baru
Metode inti	generateContent	interactions.create / get / delete
Filosofi desain	Permintaan tunggal tanpa status	Putaran tugas berstatus yang berpusat pada Interaction
Kemampuan baru ke depan	Tetap mendapat model lini utama	Kemampuan agent paling mutakhir didahulukan

🎯 Saran teknis: Kalau kamu sedang memanggil model Gemini lewat APIYI apiiyi.com, luangkan beberapa menit untuk mengecek dokumentasi resmi dan pastikan proyekmu saat ini memakai paradigma yang mana. Setelah itu, baru putuskan perlu ikut migrasi atau tidak, supaya tidak salah paham hanya karena dokumentasi default kini menampilkan Interactions API.

Perbedaan mendasar antara cara request dan manajemen state: dua paradigma

Kunci untuk memahami perbedaan keduanya ada pada “siapa yang mengelola riwayat percakapan”. generateContent mengharuskan klien untuk setiap kali request menyusun ulang seluruh array pesan historis secara lengkap. Bahkan kalau sudah masuk putaran ke-10, konten dari sembilan putaran sebelumnya tetap harus dibawa apa adanya. Cara ini sederhana dan langsung, tapi makin banyak putaran percakapan, ukuran request akan makin besar, dan konten historis yang dikirim ulang juga ikut dikenakan biaya lagi.

Interactions API menawarkan solusi: interaction id dari pemanggilan sebelumnya dipakai sebagai parameter previous_interaction_id pada request berikutnya. Server akan mengambil sendiri seluruh riwayat percakapan, sehingga klien tidak perlu lagi menyusun dan mengirim ulang secara manual. Dokumentasi resminya juga menyediakan parameter background=true untuk tugas yang berjalan lama, serta kemampuan “observable execution steps” yang memudahkan debugging dan menampilkan proses berpikir model di UI frontend. Ini sangat berguna untuk membangun produk berbasis agent.

Namun, manajemen state di sisi server juga bukan tanpa konsekuensi. Secara default, parameter store bernilai true, artinya sistem akan menyimpan record interaction — akun berbayar disimpan 55 hari, sedangkan akun gratis hanya 1 hari. Kalau karena alasan privasi atau kepatuhan Anda mengatur store=false, penyimpanan memang bisa dimatikan, tetapi dua kemampuan ini juga ikut hilang: melanjutkan percakapan lewat previous_interaction_id dan eksekusi background. Ini titik kompromi yang perlu dipikirkan dari awal.

Dari sisi biaya, dokumentasi resmi juga menegaskan nilai tambahnya: setelah state dikelola di server, riwayat percakapan yang sama tidak perlu dihitung ulang ke input token setiap kali. Akibatnya, cache hit rate meningkat cukup jelas, dan istilah yang dipakai resmi adalah “biaya lebih rendah, cache hit rate lebih tinggi”. Untuk skenario seperti chatbot layanan pelanggan atau tanya jawab dokumen panjang yang perlu menjaga banyak konteks, perbedaannya akan terasa saat volume pemanggilan sudah besar. Tapi untuk generasi satu kali atau batch processing yang memang stateless, keuntungan biaya ini hampir tidak terasa.

Ada juga detail yang sering terlewat: parameter seperti tools, system_instruction, dan generation_config — termasuk field thinking_level, temperature, dan sejenisnya — bersifat “disetel per request”. Jadi meskipun Anda melanjutkan percakapan dengan previous_interaction_id, konfigurasi tersebut tidak akan otomatis diwariskan. Setiap request tetap harus mengirimkannya lagi secara eksplisit.

Item kemampuan	generateContent	Interactions API
Pemeliharaan riwayat percakapan	Klien menyusun manual seluruh riwayat	Server mengambil otomatis lewat previous_interaction_id
Eksekusi background untuk tugas panjang	Tidak didukung	Didukung dengan background=true
Visibilitas langkah eksekusi tengah	Perlu diurai sendiri	Menyediakan observable execution steps
Kebijakan retensi record	Tidak ada konsep ini	Default disimpan, berbayar 55 hari/gratis 1 hari
Pewarisan tool dan parameter generasi	Setiap kali harus dikirim eksplisit	Setiap kali harus dikirim eksplisit, tidak otomatis diwariskan

💡 Saran pemilihan: Untuk proyek yang butuh percakapan multi-turn yang sering atau membangun workflow agent, mekanisme manajemen state di Interactions API memang bisa mengurangi banyak kode “lem”. Tapi kalau penggunaan Anda lebih banyak untuk generasi tunggal, keunggulan ini belum tentu terasa. Kami sarankan coba perbandingan traffic kecil dulu lewat platform APIYI apiyi.com sebelum memutuskan migrasi.

Kesenjangan kemampuan keduanya: siapa bisa apa, siapa belum bisa

Walaupun Interactions API adalah paradigma baru, dokumentasi resmi juga secara jelas mencantumkan kemampuan yang saat ini belum didukung. Ini penting saat memilih arsitektur; jangan cuma melihat bahwa fiturnya lebih baru lalu menganggapnya otomatis lebih lengkap.

Dokumentasi resmi menyebut bahwa Interactions API saat ini belum mendukung field video metadata pada pemahaman video, Batch API, automatic function calling di Python, serta explicit caching. Namun, implicit caching melalui previous_interaction_id tetap didukung. Sebaliknya, generateContent mendukung penuh output streaming, function calling, Batch API, explicit caching, serta input multimodal lengkap termasuk teks, gambar, audio, video, dan dokumen.

Kemampuan	generateContent	Interactions API
Batch API	✅ Didukung	❌ Belum didukung
Explicit caching	✅ Didukung	⚠️ Hanya implicit caching
Field video metadata	✅ Didukung	❌ Belum didukung
Python automatic function calling	✅ Didukung	❌ Belum didukung
Output streaming / function calling	✅ Didukung	✅ Didukung
Klaim biaya dan cache hit rate	Penagihan standar	Klaim resmi: biaya lebih rendah, hit rate lebih tinggi

Kalau pakai skenario Nano Banana image generation sebagai contoh konkret, perbedaan paling terasa ada di cara mengambil hasilnya. Interactions API menyediakan properti praktis seperti interaction.output_image dan interaction.output_text, jadi Anda bisa langsung ambil gambar atau blok teks terakhir yang dihasilkan. Sementara itu, generateContent memakai pendekatan lebih low-level lewat iterasi array candidates[0].content.parts, lalu Anda harus mengecek sendiri tipe setiap part. Buat proyek yang sudah punya logika parsing generateContent, perbedaan struktur ini biasanya berarti refactor yang lumayan besar — bukan sekadar ganti endpoint lalu selesai.

Kesenjangan ini bukan sekadar kemampuan kecil yang bisa diabaikan. Batch API biasanya jadi tulang punggung proyek yang sensitif biaya untuk memproses tugas offline dalam jumlah besar. Kalau setelah migrasi ternyata paradigma baru belum mendukungnya, artinya Anda harus mendesain ulang seluruh jalur pemrosesan offline. Begitu juga dengan explicit caching yang langsung berdampak ke biaya pada skenario konteks panjang. Kalau bisnis Anda punya system prompt panjang atau materi referensi tetap yang dipakai berulang-ulang, tanpa explicit caching Anda jadi tidak bisa mengontrol secara presisi mana yang di-cache dan berapa lama. Itulah kenapa dokumentasi resmi masih mempertahankan dua jalur teknis sekaligus, alih-alih langsung memensiunkan generateContent — setidaknya sampai kemampuan-kemampuan ini dilengkapi, ia masih belum bisa digantikan.

🔧 Saran praktik: Kalau bisnis Anda sangat bergantung pada Batch API untuk pemrosesan massal atau explicit caching untuk menekan biaya, jangan buru-buru pindah ke Interactions API. Saat ini, Anda bisa kehilangan kemampuan penting. Lebih aman untuk terus memantau pembaruan panduan migrasi resmi daripada langsung mengganti kode produksi.

APIYI网关实测：当前该用哪个范式

结论先说在前面：截至 2026 年 7 月 4 日的实测，通过 APIYI 网关调用 Gemini，应该继续使用 generateContent 原生格式。

APIYI 技术团队针对 Interactions API 的关键路径做了直接测试，覆盖了两种主流鉴权方式，结果如下。

测试端点	鉴权方式	结果
POST /v1beta2/interactions	Bearer token	❌ 404（Invalid URL）
POST /v1beta/interactions	Bearer token	❌ 404（Invalid URL）
POST /v1beta2/interactions	x-goog-api-key header	❌ 404（Invalid URL）
POST /v1beta/models/{model}:generateContent	Bearer token	✅ 正常返回

APIYI 官方文档原话是：“APIYI 网关暂不支持 Interactions API 中转——/v1beta2/interactions 与 /v1beta/interactions 路径均返回 404”，并给出明确建议：“通过 APIYI 调用 Gemini 请继续使用 generateContent 原生格式”。这也是为什么 APIYI 站内目前全部 Gemini 相关文档都统一基于 generateContent 格式编写，这样能保证读者复制代码就能直接跑通，不会遇到路径 404 的问题。

需要强调的是，这是一个动态状态，而不是永久限制。随着 Interactions API 逐渐成为官方默认范式，网关侧后续大概率会跟进支持；届时 APIYI 会更新对应文档，目前可以关注 docs.apiyi.com/api-capabilities/gemini/interactions-api 这个页面获取最新的支持状态，不需要每次都自己动手测试端点。

这组测试结果也提醒了一个容易被忽视的现实：官方文档层面的“正式可用”，和某个具体中转网关或第三方 SDK 是否已经完成适配，完全是两回事。开发者如果只看官方文档的默认展示，直接照抄 Interactions API 的代码示例塞进现有的中转配置里，大概率会先撞上 404，再花时间排查究竟是自己的代码写错了，还是网关本身还没跟上。遇到类似情况时，先确认自己的调用链路（直连官方还是经第三方中转）对新范式的支持状态，往往比反复检查业务代码更快定位问题。

🚀 快速开始: 如果你现在就想验证自己的 Gemini 调用链路是否正常，推荐直接使用 APIYI apiyi.com 的 generateContent 格式接入，该平台提供统一的 base_url，支持文本、图片等多种 Gemini 模型的调用，不需要额外处理认证细节。

该怎么选：场景化决策建议

结合前面的能力对比和实测结论，给出一份简单的场景化建议表。

Penggunaan	Rekomendasi	Alasan
Melalui APIYI 网关 memanggil Gemini	generateContent	Gateway saat ini hanya mendukung format ini, jalur Interactions API mengembalikan 404
Bergantung pada Batch API untuk pemrosesan massal	generateContent	Interactions API belum mendukung Batch API
Perlu cache eksplisit untuk menekan biaya	generateContent	Interactions API saat ini hanya punya cache implisit
Membangun agent percakapan multi-turn, direct ke API resmi	Bisa evaluasi Interactions API	Manajemen status di server bisa mengurangi logika penggabungan riwayat
Perlu melihat langkah eksekusi model untuk debugging	Interactions API	Mendukung observable execution steps secara native
Proyek yang sudah berjalan dengan generateContent	Belum perlu migrasi	legacy masih sepenuhnya didukung, dan dalam jangka pendek masih akan mendapat model baru

Singkatnya, apakah perlu migrasi atau tidak bukan ditentukan oleh “baru atau lama”, melainkan oleh apakah dependensi kamu sudah tercakup penuh oleh Interactions API, dan apakah jalur pemanggilan Gemini kamu — direct ke official API atau lewat gateway proksi — sudah mendukung paradigma baru ini. Untuk sebagian besar developer yang memanggil lewat APIYI, saat ini tetap memakai generateContent adalah pilihan yang paling aman.

Pertanyaan yang Sering Diajukan

Q1: Apakah generateContent akan dimatikan? Masih layak kah membangun proyek baru di atasnya sekarang?

Dalam jangka pendek tidak. Pihak resmi sudah menyatakan dengan jelas bahwa generateContent meski diberi label legacy, “tetap didukung sepenuhnya”, dan dalam waktu yang bisa diperkirakan masih akan terus menerima model Gemini utama yang baru. Jika Anda memanggil Gemini lewat APIYI apiyi.com, saat ini membangun proyek baru berbasis generateContent sama sekali tidak masalah; tidak perlu cemas hanya karena dokumentasi default menampilkan Interactions API.

Q2: Kapan gateway APIYI akan mendukung Interactions API?

Saat ini belum ada jadwal pasti. Ini bergantung pada seberapa luas paradigma tersebut diadopsi dalam ekosistem resmi dan seberapa cepat penyesuaian di sisi gateway. Disarankan untuk mengikuti pembaruan dokumentasi resmi platform APIYI apiyi.com. Begitu dukungan untuk proxy Interactions API tersedia, dokumentasi terkait akan segera diperbarui, jadi Anda tidak perlu terus-menerus menguji status endpoint secara manual.

Q3: Apakah dua jenis API bisa dipakai bercampur dalam proyek yang sama?

Secara teknis, selama alur pemanggilan mendukungnya, dua paradigma ini bisa hidup berdampingan. Misalnya, pakai generateContent untuk menangani tugas batch API, sementara pada skenario percakapan multi-giliran yang terhubung langsung ke API resmi mencoba Interactions API. Namun saat dipanggil lewat gateway APIYI, karena jalur Interactions API saat ini mengembalikan 404, sebaiknya sementara ini gunakan format generateContent secara seragam agar tidak ada dua logika pemanggilan yang tidak konsisten dalam satu proyek dan biaya pemeliharaan jadi lebih tinggi.

Ringkasan

Setelah Interactions API resmi dirilis pada Juni 2026, ini memang mewakili arah jangka panjang Google untuk cara pemanggilan Gemini. Kemampuan seperti pengelolaan status di sisi server dan langkah eksekusi yang bisa diamati sangat menarik untuk aplikasi agen, tetapi masih ada beberapa kekurangan besar dalam hal Batch API, cache eksplisit, dan metadata video. generateContent tetap didukung sepenuhnya dan dalam jangka pendek masih akan terus diperbarui. Yang lebih penting, berdasarkan hasil uji langsung saat memanggil Gemini melalui gateway APIYI, hingga saat ini semua jalur terkait Interactions API masih mengembalikan 404, dan generateContent adalah satu-satunya format yang bisa dipakai sekarang. Jika Anda membutuhkan pemanggilan model Gemini yang stabil dan andal, disarankan menggunakan format native generateContent lewat APIYI apiyi.com; setelah gateway mendukung paradigma baru, dokumentasinya akan segera diperbarui.

Data uji dalam artikel ini dan verifikasi informasi resmi dilakukan oleh tim teknis APIYI. Jika Anda ingin mengetahui lebih banyak detail pemanggilan model seri Gemini, silakan hubungi dukungan teknis melalui APIYI apiyi.com.

Referensi

1. Google AI for Developers – Ikhtisar Interactions API: konsep Interaction, metode inti, dan penjelasan kemampuan

   • Link: ai.google.dev/gemini-api/docs/interactions-overview

2. Google AI for Developers – generateContent（Legacy）: status dukungan API lama dan cakupan kemampuannya

   • Link: ai.google.dev/gemini-api/docs/interactions

3. Dokumentasi resmi APIYI – Status dukungan Gemini Interactions API: hasil pengujian endpoint gateway dan rekomendasi pemanggilan

   • Link: docs.apiyi.com/api-capabilities/gemini/interactions-api