API Interactions

L'API Interactions est notre nouvelle interface et le moyen le plus simple de créer des applications avec les modèles et les agents Gemini. Depuis juin 2026, elle est disponible pour tous et constitue l'interface recommandée pour tous les nouveaux projets.

Bien qu'elle soit désormais considérée comme ancienne, l'API generateContent d'origine reste entièrement compatible.

Pourquoi utiliser l'API Interactions ?

• Nouvelles fonctionnalités prêtes à l'emploi : état de conversation côté serveur facultatif à l'aide de previous_interaction_id, étapes d'exécution observables pour le débogage et le rendu de l'UI, et exécution en arrière-plan pour les tâches de longue durée à l'aide de background=true.
• Coût réduit avec des taux de succès de cache plus élevés : la gestion de l'état côté serveur permet une mise en cache du contexte plus efficace entre les tours, ce qui réduit les coûts en jetons pour les conversations multitours.
• Conçu pour les modèles et agents de pointe : conçu spécifiquement pour les modèles de réflexion, l'utilisation d'outils en plusieurs étapes et les flux de raisonnement complexes, ce qui simplifie le processus de création, de débogage et d'orchestration des applications agentiques.
• Une seule API pour les modèles et les agents : une interface unifiée pour appeler directement les modèles et les agents Gemini, tels que Deep Research et les agents personnalisés gérés. Vous n'avez pas besoin d'apprendre à utiliser des points de terminaison ou des modèles distincts.
• Où les nouveautés seront lancées : à l'avenir, les nouveaux modèles et fonctionnalités au-delà de la famille principale, ainsi que les nouvelles fonctionnalités et outils agentiques, 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 activer le comportement sans état en définissant store=false. Pour en savoir plus, consultez la section Conservation des données.

Premiers pas

• Configurez votre agent de codage : connectez-vous au MCP Gemini Docs et installez la compétence gemini-interactions-api pour donner à votre assistant un accès direct aux dernières ressources pour les développeurs et aux bonnes pratiques. Configurer votre agent de programmation →
• 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 de démarrage de l'API Interactions.

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. Un Interaction représente un tour complet dans une conversation ou une tâche. Il sert d'enregistrement de session et contient l'historique complet d'une interaction sous la forme d'une 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 côté client et les résultats (comme function_call et function_result), ainsi que le model_output final. La ressource stockée (récupérée via interactions.get) inclut également user_input étapes 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 appelez interactions.create, vous créez une 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 paramètre previous_interaction_id 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 de portée 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'intégralité de l'historique 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), de 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 demande. Cette commande est distincte de la gestion de l'état. Vous pouvez désactiver le stockage pour n'importe quelle interaction. Notez toutefois que store=false n'est pas compatible avec background=true et empêche l'utilisation de previous_interaction_id pour les tours suivants.

Vous pouvez supprimer les interactions stockées à tout moment à l'aide de la méthode de suppression disponible dans la documentation de référence de l'API. Vous ne pouvez supprimer des interactions que si vous connaissez leur ID.

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

Le système traite les objets Interaction conformément aux Conditions d'utilisation.

Bonnes pratiques

• Taux de succès du cache : l'utilisation de previous_interaction_id 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 les interactions entre l'agent et le modèle dans une conversation. Par exemple, vous pouvez utiliser un agent spécialisé, comme 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 associant ces étapes à l'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 1.55.0.
• Sur JavaScript, il s'agit du package @google/genai à partir de la version 1.33.0.

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

Limites

• MCP distant : Gemini 3 n'est pas compatible avec le MCP distant. Cette fonctionnalité sera bientôt disponible.

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 : champ video_metadata utilisé pour définir les intervalles de découpage et les fréquences d'images personnalisées pour la compréhension des vidéos.
• API Batch
• 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.

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 Gemini Deep Research