API Interactions

L'API Interactions est le moyen le plus simple et le plus efficace de créer des solutions avec les modèles et les agents Gemini. Depuis juin 2026, elle est disponible pour tous et recommandée pour tous les nouveaux projets. Bien qu'elle soit désormais considérée comme une API héritée, l'API generateContent d'origine reste entièrement compatible.

Pourquoi utiliser l'API Interactions ?

• Interface universelle pour toutes les applications : conçue comme l'interface standard pour tous les cas d'utilisation, y compris la génération de texte en une seule étape, la compréhension multimodale, les sorties structurées, l'orchestration d'outils et les workflows d'agent.
• Une seule API pour les modèles et les agents : un point de terminaison et un modèle unifiés pour appeler directement les modèles Gemini standards, ainsi que des agents spécialisés (tels que Deep Research et les agents gérés personnalisés).
• Nouvelles fonctionnalités prêtes à l'emploi : fonctionnalités telles que l'état de conversation côté serveur facultatif à l'aide de previous_interaction_id, les étapes d'exécution observables pour le débogage et le rendu de l'interface utilisateur, et l'exécution en arrière-plan pour les tâches de longue durée à l'aide de background=true.
• Coût inférieur avec des taux d'accès au cache plus élevés : lors de l'utilisation de conversations en plusieurs étapes, la gestion de l'état côté serveur facultative permet une mise en cache plus efficace du contexte entre les étapes, ce qui réduit les coûts liés aux jetons.
• Lancement de nouvelles fonctionnalités : à l'avenir, tous les nouveaux modèles, fonctionnalités multimodales, outils et fonctionnalités d'agent seront lancés sur l'API Interactions.

Par défaut, l'API Interactions stocke les requêtes afin que vous puissiez exploiter les fonctionnalités de gestion de l'état côté serveur à l'aide de previous_interaction_id. Vous pouvez choisir un comportement sans état en définissant store=false. Pour en savoir plus, consultez la section Conservation des données pour détails.

Premiers pas

• Configurer votre agent de codage : connectez-vous au MCP de la documentation Gemini et installez la compétence gemini-interactions-api pour donner à votre assistant un accès direct à la documentation pour les développeurs et aux bonnes pratiques les plus récentes. Configurer votre agent de codage →
• Migrer depuis generateContent : si vous disposez d'une intégration existante, suivez le guide de migration pour passer à l'API Interactions.
• Premiers pas : consultez le guide Premiers pas avec l'API Interactions guide.

Guides des fonctionnalités

Découvrez les fonctionnalités spécifiques de l'API Interactions grâce à ces guides. Vous pouvez utiliser le bouton bascule sur ces pages pour passer de l'API generateContent à l'API Interactions :

• Génération de texte
• Génération d'images
• Compréhension des images
• Compréhension audio
• Compréhension des vidéos
• Traitement de documents
• Appel de fonction
• Sortie structurée
• Agent Deep Research
• Inférence Flex
• Inférence prioritaire

Fonctionnement de l'API Interactions

L'API Interactions est axée sur une ressource principale : Interaction. Une Interaction représente une étape complète dans une conversation ou une tâche. Elle fait office d'enregistrement de session, contenant l'historique complet d'une interaction sous forme de séquence chronologique d'étapes d'exécution. Ces étapes incluent les réflexions du modèle, les appels d'outils côté serveur ou client et les résultats (tels que function_call et function_result), ainsi que la model_output finale. La ressource stockée (récupérée via interactions.get) inclut également des étapes user_input pour un contexte complet, bien que la réponse interactions.create ne renvoie que les étapes générées par le modèle.

Lorsque vous effectuez un appel à interactions.create, vous créez une nouvelle ressource Interaction.

Gestion de l'état côté serveur

Vous pouvez utiliser le id d'une interaction terminée dans un appel ultérieur à l'aide du previous_interaction_id paramètre pour poursuivre la conversation. Le serveur utilise cet ID pour récupérer l'historique des conversations, ce qui vous évite d'avoir à renvoyer l'intégralité de l'historique des discussions.

Le paramètre previous_interaction_id ne conserve que l'historique des conversations (entrées et sorties) à l'aide de previous_interaction_id. Les autres paramètres sont définis au niveau de l'interaction et ne s'appliquent qu'à l'interaction spécifique que vous générez actuellement :

• tools
• system_instruction
• generation_config (y compris thinking_level, temperature, etc.)

Cela signifie que vous devez spécifier à nouveau ces paramètres dans chaque nouvelle interaction si vous souhaitez qu'ils s'appliquent. Cette gestion de l'état côté serveur est facultative. Vous pouvez également fonctionner en mode sans état en envoyant l'historique complet des conversations dans chaque requête.

Stockage et conservation des données

Par défaut, l'API stocke tous les objets Interaction (store=true) afin de simplifier l'utilisation des fonctionnalités de gestion de l'état côté serveur (avec previous_interaction_id), l'exécution en arrière-plan (à l'aide de background=true) et à des fins d'observabilité.

• Niveau payant : le système conserve les interactions pendant 55 jours.
• Niveau sans frais : le système conserve les interactions pendant un jour.

Si vous ne le souhaitez pas, vous pouvez définir store=false dans votre requête. Cette commande est distincte de la gestion de l'état. Vous pouvez désactiver le stockage pour n'importe quelle interaction. Toutefois, notez que store=false n'est pas compatible avec l'exécution en arrière-plan et empêche l'utilisation previous_interaction_id pour les étapes suivantes.

Pour les projets de niveau payant, vous pouvez configurer la période de conservation dans AI Studio afin de marquer automatiquement les journaux à supprimer du stockage du projet après 7, 14, 28 ou 55 jours. Une période de conservation plus courte peut affecter la récupération des conversations passées.

Vous pouvez supprimer les interactions stockées à tout moment à l'aide de la delete méthode par programmation, ce qui nécessite l'ID d'interaction. Vous pouvez également afficher et gérer les journaux d'interactions stockés, y compris la suppression du stockage du projet, dans AI Studio.

Une fois la période de conservation expirée, vos données seront automatiquement supprimées.

Les objets Interactions sont traités conformément aux conditions d'utilisation.

Afficher les interactions dans AI Studio

L'API stocke les requêtes de l'API Interactions exécutées avec store=true pour les projets de niveau payant. Vous pouvez les afficher directement depuis la page "Journaux" de Google AI Studio. Pour en savoir plus, consultez le guide des journaux.

Bonnes pratiques

• Taux d'accès au cache : la mise en cache implicite est compatible avec les modes avec état et sans état (voir le guide de démarrage rapide). L'utilisation de previous_interaction_id (avec état) pour poursuivre les conversations permet au système d'utiliser plus facilement la mise en cache implicite pour l'historique des conversations, ce qui améliore les performances et réduit les coûts.
• Mélanger les interactions : vous pouvez mélanger et associer les interactions d'agent et de modèle au sein d'une conversation. Par exemple, vous pouvez utiliser un agent spécialisé, tel que l'agent Deep Research, pour la collecte initiale de données, puis utiliser un modèle Gemini standard pour les tâches de suivi telles que la synthèse ou le reformatage, en liant ces étapes avec previous_interaction_id.

Modèles et agents compatibles

SDK

Vous pouvez utiliser la dernière version des SDK Google GenAI pour accéder à l'API Interactions.

• Sur Python, il s'agit du package google-genai à partir de la version 2.3.0.
• Sur JavaScript, il s'agit du package @google/genai à partir de la version 2.3.0.

Pour savoir comment installer les SDK, consultez la page Bibliothèques.

Limites

• MCP à distance : Gemini 3 n'est pas compatible avec le MCP à distance, mais cette fonctionnalité sera bientôt disponible.
• Compatibilité des modèles en plusieurs étapes : lorsque vous mélangez différents modèles dans une conversation (avec ou sans état), les modèles suivants doivent être compatibles avec les modalités de sortie des modèles précédents en tant qu'entrée. Par exemple, si vous générez une image à l'aide de gemini-3.1-flash-image, vous ne pouvez pas poursuivre cette conversation avec un modèle qui n'accepte pas les entrées d'image (comme un modèle de texte uniquement ou un modèle de génération de musique comme Lyria).

Les fonctionnalités suivantes sont compatibles avec l'API generateContent, mais ne sont pas encore disponibles dans l'API Interactions :

• Métadonnées vidéo : le champ video_metadata, utilisé pour définir des intervalles de découpage et des fréquences d'images personnalisées pour la compréhension vidéo.
• API par lot
• Appel de fonction automatique (Python)
• Mise en cache explicite : notez que la mise en cache implicite côté serveur est disponible dans l'API Interactions via previous_interaction_id.
• Paramètres de sécurité : les paramètres de sécurité personnalisés ne sont pas compatibles avec l'API Interactions.

Commentaires

Vos commentaires sont essentiels au développement de l'API Interactions. Partagez vos commentaires, signalez des bugs ou demandez des fonctionnalités sur notre forum de la communauté des développeurs Google AI.

Étape suivante

• Essayez le notebook de démarrage rapide de l'API Interactions.
• En savoir plus sur l'agent Deep Research de Gemini.