API Interactions

L'API Interactions est la nouvelle norme pour créer des applications avec Gemini. Elle est recommandée pour tous les nouveaux projets. Elle est optimisée pour les workflows d'agent, la gestion de l'état côté serveur et les conversations multimodales et multitours complexes. L'API generateContent d'origine reste entièrement compatible.

Pourquoi utiliser l'API Interactions ?

  • Gestion de l'historique côté serveur : flux multitours simplifiés via previous_interaction_id. Le serveur active l'état par défaut (store=true), mais vous pouvez opter pour un comportement sans état en définissant store=false.
  • Étapes d'exécution observables : les étapes typées facilitent le débogage des flux complexes et le rendu de l'interface utilisateur pour les événements intermédiaires (comme les pensées ou les widgets de recherche).
  • Conçue pour les workflows d'agent : prise en charge native de l'utilisation d'outils en plusieurs étapes, de l'orchestration et des flux de raisonnement complexes via des étapes d'exécution typées.
  • Tâches longues et en arrière-plan : prend en charge le déchargement des opérations gourmandes en ressources, telles que Deep Think et Deep Research, vers des processus en arrière-plan à l’aide de background=true.
  • Accès à de nouveaux modèles et capacités : à l'avenir, les nouveaux modèles au-delà de la famille principale, ainsi que les nouvelles capacités agentiques et outils, seront lancés exclusivement sur l'API Interactions.

Utilisez l'API Interactions si vous démarrez un nouveau projet, créez des applications d'agent ou avez besoin d'une gestion des conversations côté serveur. Utilisez generateContent si vous disposez d'une intégration existante qui répond à vos besoins ou si vous avez besoin d'une fonctionnalité qui n'est pas encore disponible dans l'API Interactions, comme l'API Batch ou la mise en cache explicite.

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 dernière documentation pour les développeurs et aux bonnes pratiques. 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.
  • Essayer le guide de démarrage rapide : commencez par un exemple de travail minimal dans le guide de démarrage rapide 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 generateContent à l'API Interactions :

Fonctionnement de l'API Interactions

L'API Interactions est axée sur une ressource principale : Interaction. Une Interaction représente un tour complet 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 pensées du modèle, les appels et les résultats d'outils côté serveur ou côté client (comme 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.

Accéder aux sorties avec les propriétés pratiques du SDK

Bien que l'API Interactions renvoie une chronologie structurée des étapes d'exécution (telles que les pensées, les requêtes de recherche et les appels de fonction), vous n'avez pas besoin de parcourir manuellement les étapes pour obtenir la réponse finale du modèle.

Les SDK Google GenAI fournissent des propriétés pratiques directement sur l'objet Interaction renvoyé pour accéder aux sorties de différentes modalités :

Propriété pratique du SDK Type renvoyé Description
interaction.output_text Chaîne Renvoie les derniers blocs de texte dans la réponse du modèle. Si la réponse est divisée en plusieurs blocs TextContent consécutifs, elle les joint automatiquement. Elle n'inclut pas les blocs de texte précédents séparés par du contenu non textuel (comme des pensées, des images, de l'audio ou des appels d'outils). Pour les réponses multimodales complexes ou entrelacées, vous devez itérer manuellement sur steps.
interaction.output_image ImageContent ou None Renvoie le dernier bloc d'image généré par le modèle dans la requête actuelle.
interaction.output_audio AudioContent ou None Renvoie le dernier bloc audio généré par le modèle dans la requête actuelle.

Pour les cas d'utilisation avancés, tels que le rendu des processus de réflexion intermédiaires, l'inspection des appels d'outils étape par étape ou le débogage, vous pouvez toujours inspecter et parcourir manuellement la chronologie interaction.steps brute.

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 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.

Bonnes pratiques

  • Taux de réussite 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élange d'interactions : vous pouvez mélanger et faire correspondre les interactions d'agent et de modèle dans 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

Nom du modèle Type ID du modèle
Gemini 3.5 Flash Modèle gemini-3.5-flash
Gemini 3.1 Flash-Lite Modèle gemini-3.1-flash-lite
Preview Gemini 3.1 Flash-Lite Modèle gemini-3.1-flash-lite-preview
Gemini 3.1 Pro (preview) Modèle gemini-3.1-pro-preview
Preview Gemini 3 Flash Modèle gemini-3-flash-preview
Gemini 2.5 Pro Modèle gemini-2.5-pro
Gemini 2.5 Flash Modèle gemini-2.5-flash
Gemini 2.5 Flash-Lite Modèle gemini-2.5-flash-lite
Preview Lyria 3 Clip Modèle lyria-3-clip-preview
Preview Lyria 3 Pro Modèle lyria-3-pro-preview
Preview Deep Research Agent deep-research-pro-preview-12-2025
Preview Deep Research Agent deep-research-preview-04-2026
Preview Deep Research Agent deep-research-max-preview-04-2026

SDK

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

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

Pour en savoir plus sur l'installation des SDK, consultez la page Bibliothèques.

Limites

  • État bêta : l'API Interactions est en version bêta/preview. Les fonctionnalités et les schémas peuvent changer.
  • MCP à distance : Gemini 3 ne prend pas en charge le MCP à distance. 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 :

Modifications importantes

L'API Interactions est actuellement en version bêta. Nous développons et affinons activement les fonctionnalités de l'API, les schémas de ressources et les interfaces SDK en fonction de l'utilisation réelle et des commentaires des développeurs. Par conséquent, des modifications importantes peuvent se produire.

Modifications importantes existantes :

  • Schéma des étapes : un nouveau tableau d'étapes remplace le tableau de sorties, fournissant une chronologie structurée de chaque tour d'interaction.

Pour en savoir plus sur la dernière modification importante et comprendre comment migrer, consultez le guide de migration des modifications importantes (mai 2026).

D'autres mises à jour potentielles peuvent inclure des modifications des schémas d'entrée et de sortie, des signatures de méthode SDK et des structures d'objet, ainsi que des comportements de fonctionnalités spécifiques.

Pour les charges de travail de production, vous devez continuer à utiliser l'API standard generateContent. Elle reste la voie recommandée pour les déploiements stables, et nous continuerons à la développer et à la maintenir activement.

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