Gemini Interactions API et generateContent : comment choisir ? 4 tableaux pour clarifier la comparaison la plus récente de 2026

打开 la documentation officielle de Gemini, en particulier les pages comme la génération d’images Nano Banana, vous avez peut-être remarqué qu’en haut de la page apparaît un nouveau sélecteur : d’un côté Interactions API, de l’autre generateContent API. Ce n’est pas qu’une simple refonte de la documentation : Google a officiellement fait passer Interactions API en GA (disponibilité générale) en juin 2026 et recommande désormais à tous les nouveaux projets de l’adopter en priorité. Cet article, basé sur la documentation officielle et sur les tests réels effectués via la passerelle APIYI, vous explique clairement les différences clés, les écarts de capacités et les recommandations concrètes pour l’appel.

Valeur clé : à la fin de l’article, vous saurez précisément en quoi Interactions API et generateContent diffèrent dans leur philosophie de conception, leur gestion d’état et leur couverture fonctionnelle, et vous saurez aussi quel paradigme choisir pour invoquer Gemini via APIYI.

Différences clés entre Interactions API et generateContent

Commençons par la conclusion : ces deux API ne sont pas simplement liées par une logique de montée de version, mais correspondent à deux philosophies de conception différentes. generateContent suit un modèle sans état, de type « une requête, une réponse » ; le client doit gérer lui-même l’historique complet de la conversation. Interactions API, de son côté, délègue la gestion d’état au serveur et redessine tout le mécanisme d’interaction autour d’un nouveau concept : l’« Interaction ».

La documentation officielle définit une Interaction comme « un tour complet de conversation ou de tâche », composé en interne d’une série d’étapes exécutées dans l’ordre chronologique, incluant le raisonnement du modèle, les appels d’outils et leurs résultats, ainsi que la sortie finale du modèle. Autrement dit, Interactions API a été pensée dès le départ pour les conversations multi-tours et les tâches de type agent, pas seulement pour des questions-réponses ponctuelles.

Cela explique aussi pourquoi Google parle de « disponibilité générale » plutôt que d’une simple « nouvelle fonctionnalité ». Interactions API est entrée en bêta publique en décembre 2025, puis a été officiellement annoncée en GA en juin 2026. Le blog officiel indique clairement : « Nous recommandons à tous les nouveaux projets et applications d’utiliser Interactions API ». Toute la documentation officielle affiche désormais cette nouvelle approche par défaut, et Google pousse aussi les SDK tiers et les partenaires de l’écosystème à en faire leur interface de référence. En d’autres termes, il ne s’agit pas d’une mise à jour optionnelle, mais d’une redéfinition de la manière d’appeler Gemini ; Google fournit simplement un guide de migration pour laisser les développeurs avancer à leur rythme, sans imposer un basculement brutal.

Dimension de comparaison	generateContent (legacy)	Interactions API
Statut actuel	Héritée, mais toujours entièrement prise en charge	GA officiel à partir de juin 2026
Recommandation officielle	Peut continuer à être utilisée dans les projets existants	Recommandée en priorité pour tous les nouveaux projets
Méthode principale	generateContent	interactions.create / get / delete
Philosophie de conception	Requête unique sans état	Tâches par tours, avec état, centrées sur Interaction
Nouvelles capacités futures	Continue de recevoir les nouveaux modèles du flux principal	Les capacités agent de pointe arrivent en priorité

🎯 Conseil technique : si vous invoquez les modèles Gemini via APIYI apiyi.com, prenez quelques minutes pour vérifier dans la documentation officielle quel paradigme votre projet utilise actuellement, puis décidez s’il faut migrer. Vous éviterez ainsi de croire, à cause de l’affichage par défaut de la doc, que votre code existant est déjà obsolète.

Différences essentielles entre les deux approches de requête et de gestion d’état

La clé pour comprendre la différence entre les deux, c’est de savoir « qui maintient l’historique de la conversation ». generateContent oblige le client à reconstituer à chaque requête l’ensemble des messages précédents dans un tableau complet ; même au dixième tour, il faut renvoyer tels quels les neuf tours précédents. C’est simple et direct, mais plus la conversation s’allonge, plus le corps de la requête grossit, et plus l’historique est retransmis — donc refacturé — en boucle.

L’Interactions API propose une autre approche : on reprend l’interaction id renvoyé par l’appel précédent et on le transmet comme paramètre previous_interaction_id à la requête suivante. Le serveur récupère alors automatiquement tout l’historique de la conversation, sans que le client ait à le reconstruire ni à le retransmettre. La documentation officielle propose aussi background=true pour les tâches longues, ainsi qu’une capacité d’« observable execution steps », utile pour le debug et pour afficher le raisonnement intermédiaire du modèle dans l’UI front, ce qui est particulièrement intéressant pour construire des produits de type agent.

En revanche, la gestion d’état côté serveur a aussi un coût. Par défaut, le paramètre store vaut true, ce qui signifie que le système conserve l’enregistrement de l’interaction — 55 jours pour les comptes payants, 1 jour pour les comptes gratuits. Si, pour des raisons de confidentialité ou de conformité, vous passez store à false, vous pouvez bien désactiver le stockage, mais vous perdez aussi la reprise de conversation via previous_interaction_id et l’exécution en arrière-plan. C’est un vrai point d’arbitrage à anticiper.

Côté coût, l’éditeur avance un argument clair : une fois l’état maintenu par le serveur, le contenu historique d’une même conversation n’a plus besoin d’être reconsommé à chaque fois dans les tokens d’entrée, ce qui améliore nettement le taux de cache. La formulation officielle est d’ailleurs « un coût plus bas, un taux de cache plus élevé ». Pour un chatbot de support, ou des cas comme la question-réponse sur de longs documents, la différence devient assez visible dès que le volume d’appels monte. En revanche, pour de la génération en un seul tour ou du traitement par lots, cet avantage compte peu, voire pas du tout.

Un autre détail facile à rater : les paramètres tools, system_instruction et generation_config — y compris thinking_level, temperature, etc. — sont définis « à chaque appel ». Même si vous reprenez une conversation avec previous_interaction_id, ces réglages ne sont pas hérités automatiquement : il faut les renvoyer explicitement à chaque requête.

Élément	generateContent	Interactions API
Maintenance de l’historique de conversation	Le client assemble manuellement tout l’historique	Le serveur récupère automatiquement via previous_interaction_id
Exécution en arrière-plan pour les tâches longues	Non pris en charge	Pris en charge avec background=true
Visibilité des étapes d’exécution intermédiaires	À analyser soi-même	Fournit des observable execution steps
Politique de conservation des enregistrements	Pas de notion équivalente	Conservation par défaut, 55 jours payant / 1 jour gratuit
Héritage des outils et paramètres de génération	À renvoyer explicitement à chaque fois	À renvoyer explicitement à chaque fois, pas d’héritage automatique

💡 Conseil de choix : pour des projets qui impliquent beaucoup de dialogues multi-tours ou des workflows d’agent, le mécanisme d’état de l’Interactions API peut clairement vous éviter pas mal de code « colle ». Mais si vos appels sont surtout des générations ponctuelles, cet avantage ne se verra pas forcément ; dans ce cas, on vous conseille de faire d’abord un test à faible trafic via la plateforme APIYI apiyi.com avant de décider si la migration vaut vraiment le coup.

Les écarts de capacité entre les deux : ce que l’un sait faire, et pas encore l’autre

L’Interactions API repose bien sur un nouveau paradigme, mais la documentation officielle liste aussi clairement les capacités qui ne sont pas encore prises en charge. C’est un point à intégrer dans le choix technique : il ne faut pas supposer qu’« plus récent » veut dire « plus complet ».

La documentation indique explicitement que l’Interactions API ne prend pas encore en charge le champ video metadata pour la compréhension vidéo, ni Batch API, ni l’automatic function calling en Python, ni le cache explicite (explicit caching). En revanche, le cache implicite basé sur previous_interaction_id est bien supporté. À l’inverse, generateContent prend entièrement en charge la sortie en streaming, les appels de fonctions, Batch API, le cache explicite, ainsi que les entrées multimodales complètes : texte, image, audio, vidéo et document.

Capacité	generateContent	Interactions API
Batch API	✅ Pris en charge	❌ Pas encore pris en charge
Cache explicite (explicit caching)	✅ Pris en charge	⚠️ Cache implicite uniquement
Champ video metadata	✅ Pris en charge	❌ Pas encore pris en charge
Appel automatique de fonctions en Python	✅ Pris en charge	❌ Pas encore pris en charge
Sortie en streaming / appels de fonctions	✅ Pris en charge	✅ Pris en charge
Coût annoncé et taux de cache	Facturation standard	L’éditeur annonce un coût plus bas et un meilleur taux de cache

Dans le cas très concret de la génération d’images Nano Banana, la différence la plus visible se situe dans la manière de récupérer le résultat. L’Interactions API fournit des propriétés pratiques comme interaction.output_image et interaction.output_text, qui donnent directement accès à l’image ou au bloc de texte final. Avec generateContent, on passe par une structure plus bas niveau, en parcourant le tableau candidates[0].content.parts, et il faut déterminer soi-même le type de chaque part. Pour un projet qui a déjà une logique de parsing basée sur generateContent, ce changement de structure implique souvent une vraie refonte du code — on ne peut pas juste remplacer l’endpoint et considérer que c’est réglé.

Ces écarts ne sont pas des détails. Batch API est souvent un levier central pour les projets sensibles au coût qui traitent des tâches hors ligne en lot. Si vous migrez et découvrez que la nouvelle approche ne le prend pas en charge, cela revient à devoir redessiner toute la chaîne de traitement offline. Le cache explicite, lui, joue directement sur le coût dans les scénarios à grand contexte : si votre activité repose sur de longs system prompt fixes ou des documents de référence à réutiliser souvent, ne pas avoir de cache explicite veut dire que vous ne pouvez plus contrôler précisément ce qui est mis en cache, ni pendant combien de temps. C’est aussi pour ça que la documentation officielle garde les deux lignes techniques en parallèle, au lieu de faire disparaître generateContent tout de suite. Tant que ces capacités ne sont pas toutes comblées, il reste irremplaçable.

🔧 Conseil pratique : si votre activité dépend fortement de Batch API pour le traitement par lots ou du cache explicite pour réduire les coûts, mieux vaut éviter de basculer trop vite vers l’Interactions API. Attendez plutôt le rythme d’évolution du guide de migration officiel, au lieu de modifier immédiatement le code de production.

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

Conclusion d’abord : d’après les tests effectués au 4 juillet 2026, pour appeler Gemini via la passerelle APIYI, il faut continuer à utiliser le format natif generateContent.

L’équipe technique d’APIYI a effectué des tests directs sur les chemins critiques de l’Interactions API, en couvrant les deux principales méthodes d’authentification. Résultat :

Endpoint de test	Méthode d’authentification	Résultat
POST /v1beta2/interactions	Bearer token	❌ 404 (Invalid URL)
POST /v1beta/interactions	Bearer token	❌ 404 (Invalid URL)
POST /v1beta2/interactions	en-tête x-goog-api-key	❌ 404 (Invalid URL)
POST /v1beta/models/{model}:generateContent	Bearer token	✅ Réponse normale

La documentation officielle d’APIYI le dit clairement : « la passerelle APIYI ne prend pas encore en charge la médiation de l’Interactions API — les chemins /v1beta2/interactions et /v1beta/interactions renvoient tous deux une 404 », puis recommande explicitement : « pour appeler Gemini via APIYI, continuez à utiliser le format natif generateContent ». C’est aussi pour cela que, sur le site d’APIYI, toute la documentation Gemini est actuellement uniformisée autour du format generateContent : les lecteurs peuvent copier le code et l’exécuter directement, sans tomber sur une 404 liée au chemin.

Il faut insister sur un point : c’est un état dynamique, pas une limitation permanente. À mesure que l’Interactions API deviendra le paradigme par défaut côté officiel, la passerelle devrait logiquement le prendre en charge à son tour ; APIYI mettra alors à jour la documentation correspondante. Pour l’instant, vous pouvez suivre la page docs.apiyi.com/api-capabilities/gemini/interactions-api pour connaître le statut de support le plus récent, sans avoir besoin de retester les endpoints à chaque fois.

Ces résultats rappellent aussi une réalité souvent négligée : le fait qu’une fonctionnalité soit « officiellement disponible » dans la doc ne veut pas dire qu’une passerelle de proxy API ou un SDK tiers l’a déjà intégrée. Si l’on se contente du comportement par défaut de la documentation officielle et qu’on colle directement les exemples de code de l’Interactions API dans une configuration de proxy existante, on risque très probablement de se heurter d’abord à une 404, puis de perdre du temps à déterminer si l’erreur vient du code ou du fait que la passerelle n’a tout simplement pas encore suivi. Dans ce genre de cas, vérifier d’abord si votre chaîne d’appel — connexion directe à l’officiel ou passage par un intermédiaire — supporte déjà le nouveau paradigme permet souvent de trouver le problème bien plus vite que de refaire dix fois la revue du code métier.

🚀 Démarrage rapide : si vous voulez vérifier tout de suite que votre chaîne d’appel Gemini fonctionne correctement, nous vous recommandons d’utiliser directement le format generateContent via APIYI apiyi.com. La plateforme fournit un base_url unifié, prend en charge les appels à plusieurs modèles Gemini, notamment pour le texte et l’image, et ne demande pas de traitement supplémentaire des détails d’authentification.

Comment choisir : recommandations par scénario

En combinant la comparaison des capacités et les résultats des tests ci-dessus, voici une grille simple de recommandations selon les cas d’usage.

Cas d’usage	Solution recommandée	Pourquoi
Appeler Gemini via la passerelle APIYI	generateContent	La passerelle ne prend actuellement en charge que ce format ; le chemin Interactions API renvoie 404
Dépendre de Batch API pour du traitement par lots	generateContent	L’Interactions API ne prend pas encore en charge Batch API
Avoir besoin d’un cache explicite pour réduire les coûts	generateContent	L’Interactions API ne propose pour l’instant qu’un cache implicite
Construire un agent de conversation multi-tours en connexion directe à l’API officielle	Interactions API à évaluer	La gestion d’état côté serveur évite d’avoir à recoller l’historique
Vouloir observer les étapes intermédiaires d’exécution du modèle pour le débogage	Interactions API	Support natif des étapes d’exécution observables
Projet existant déjà opérationnel avec generateContent	Ne pas migrer pour l’instant	Le mode legacy reste pleinement supporté et continuera à recevoir de nouveaux modèles à court terme

En résumé, le choix de migration ne dépend pas de savoir si une solution est « plus récente », mais de savoir si vos dépendances sont déjà entièrement couvertes par l’Interactions API et si votre chaîne d’appel Gemini — directe ou via une passerelle de proxy — la prend déjà en charge. Pour la plupart des développeurs qui passent par APIYI, garder generateContent reste aujourd’hui l’option la plus sûre.

Questions fréquentes

Q1 : generateContent sera-t-il déprécié ? Est-ce encore pertinent de lancer un nouveau projet dessus ?

À court terme, non. L’official a clairement indiqué que, même si generateContent est marqué comme legacy, il est « toujours entièrement pris en charge » et continuera à recevoir les nouveaux modèles Gemini principaux dans un avenir prévisible. Si vous appelez Gemini via APIYI apiyi.com, vous pouvez tout à fait développer un nouveau projet sur generateContent à ce stade ; pas besoin de s’inquiéter parce que la documentation affiche par défaut Interactions API.

Q2 : Quand la passerelle APIYI prendra-t-elle en charge Interactions API ?

Il n’y a pas de calendrier précis pour l’instant. Cela dépend du degré d’adoption de ce paradigme dans l’écosystème officiel et de l’avancement de l’adaptation côté passerelle. Nous vous conseillons de suivre les mises à jour de la documentation officielle de la plateforme APIYI apiyi.com : dès que le relais d’Interactions API sera pris en charge, la documentation correspondante sera mise à jour immédiatement, sans que vous ayez besoin de retester en boucle l’état des endpoints.

Q3 : Peut-on mélanger les deux API dans un même projet ?

D’un point de vue technique, tant que la chaîne d’appel le permet, les deux paradigmes peuvent coexister. Par exemple, vous pouvez utiliser generateContent pour traiter des tâches Batch API, tout en testant Interactions API dans des scénarios de dialogue multi-tours en connexion directe avec l’API officielle. En revanche, via la passerelle APIYI, comme le chemin Interactions API renvoie actuellement une 404, il est recommandé de rester pour l’instant sur le format generateContent afin d’éviter d’avoir deux logiques d’appel incohérentes dans un même projet et d’alourdir la maintenance.

Conclusion

Après sa mise en version stable en juin 2026, Interactions API représente bien l’orientation de long terme de Google pour l’appel à Gemini. La gestion d’état côté serveur et les étapes d’exécution observables sont très attractives pour les applications de type agent, mais il reste encore des lacunes nettes sur Batch API, le cache explicite et les métadonnées vidéo. generateContent reste entièrement pris en charge et continuera d’évoluer à court terme. Plus important encore, d’après nos tests via la passerelle APIYI, tous les chemins liés à Interactions API renvoient encore une 404 à ce jour ; generateContent est donc le seul format actuellement utilisable. Si vous avez besoin d’un appel stable et fiable aux modèles Gemini, nous vous recommandons de passer par APIYI apiyi.com en utilisant le format natif generateContent ; la documentation sera mise à jour dès que la passerelle prendra en charge le nouveau paradigme.

Les données de test de cet article et la vérification des informations officielles ont été réalisées par l’équipe technique d’APIYI. Pour en savoir plus sur les détails d’appel des modèles Gemini, n’hésitez pas à contacter le support technique via APIYI apiyi.com.

Références

1. Google AI for Developers – Vue d’ensemble de l’Interactions API : concept d’interaction, méthodes clés et capacités

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

2. Google AI for Developers – generateContent（Legacy） : état de prise en charge de l’API héritée et périmètre des capacités

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

3. Documentation officielle APIYI – Statut de prise en charge de Gemini Interactions API : résultats des endpoints testés sur le gateway et recommandations d’appel

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