L'API Interactions fournit une interface unifiée avec état pour créer des applications d'IA générative et des workflows agentiques à l'aide de modèles et d'agents Gemini hébergés sur Gemini Enterprise Agent Platform. L'API generateContent reste entièrement compatible avec l'API Interactions.
Pourquoi utiliser l'API Interactions ?
L'API Interactions offre plusieurs avantages clés pour créer des applications d'IA générative et des workflows agentiques :
- API unique pour les modèles et les agents : un point de terminaison et un modèle unifiés pour appeler directement des modèles Gemini standards ainsi que des agents spécialisés (comme l'agent Gemini 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 l'affichage de l'UI, et l'exécution en arrière-plan pour les tâches de longue durée à l'aide debackground=true.
Fonctionnement de l'API Interactions
L'API Interactions est centrée sur la ressource Interaction. Un Interaction représente un tour complet dans une conversation ou une tâche, et sert d'enregistrement de session contenant une séquence chronologique d'steps d'exécution :
user_input: messages d'entrée, fichiers multimodaux ou résultats d'outils fournis pour le tour. Les interactions stockées récupérées avecinteractions.getincluent les étapesuser_inputpour un contexte complet, tandis que les réponsesinteractions.createne renvoient que les étapes générées au cours de ce tour.thought: résumés de raisonnement intermédiaires générés par le modèle ou l'agent lors de la planification de sa réponse.- Étapes d'appel d'outil et de résultat : appels et sorties d'outils côté client ou côté serveur (tels que
function_calletfunction_result). model_output: texte final, JSON structuré ou contenu multimodal produit par le modèle ou l'agent.
Lorsque vous appelez interactions.create, Agent Platform traite votre entrée, exécute les outils côté serveur ou les boucles d'agent configurés, puis renvoie la ressource Interaction obtenue. Pour obtenir des exemples de code en Python, TypeScript/JavaScript et REST, consultez le guide du développeur de l'API Interactions.
Modèles compatibles
Les modèles Gemini suivants sont compatibles avec l'API Interactions :
Cliquez pour développer la liste des modèles compatibles
- Gemini Omni Flash
- Gemini Omni 1.2 Flash
- Gemini Omni 1.1 Flash
- Gemini 4 Hydrogen
- Gemini 4 Carbon pour la cybersécurité
- Gemini 4 Carbon
- Gemini 4 Argon Cyber Permissive
- Gemini 4 Argon
- Gemini 3.8 Flash Cyber
- Gemini 3.8 Flash
- Gemini 3.7 Flash
- Gemini 3.6 Flash
- Gemini 3.5 Flash-Lite
- Gemini 3.5 Flash
- Gemini 3.1 Pro
- Gemini 3.1 Flash-Lite
En plus des modèles Gemini de la liste précédente, l'API Interactions est compatible avec les modèles de musique générative suivants :
* lyria-3-clip-preview et lyria-3-pro-preview : modèles de musique générative pour les clips audio haute fidélité et la composition de chansons complètes (compatibles avec les interactions sans état uniquement avec store=false).
Agents compatibles
Vous pouvez appeler les agents suivants via l'API Interactions en spécifiant le paramètre agent au lieu de model :
antigravity-preview-05-2026: agent autonome à usage général conçu pour le raisonnement en plusieurs étapes, le codage, les opérations sur les fichiers et l'utilisation d'outils.deep-research-preview-04-2026: Agent Gemini Deep Research conçu pour la recherche et la synthèse autonomes et en plusieurs étapes sur le Web.- Agents gérés personnalisés déployés sur Agent Platform.
Fonctionnalités et caractéristiques
Les sections suivantes décrivent les fonctionnalités de base, les caractéristiques techniques et les considérations opérationnelles de l'API Interactions.
Gestion de l'état
Par défaut, l'API Interactions stocke les interactions sur le serveur (store=true) pendant sept jours afin que vous puissiez enchaîner des conversations multitours avec previous_interaction_id et exécuter des tâches asynchrones en arrière-plan (background=true). Pour activer l'exécution sans état et prendre en charge les workflows de conservation des données zéro (ZDR), définissez store=false. Pour en savoir plus, consultez Gérer le stockage des sessions et l'état des conversations.
Limites de requêtes et limites multimodales
L'API Interactions applique les limites suivantes pour la charge utile des requêtes et les entrées multimodales :
- Limites de charge utile des requêtes : la charge utile de la requête HTTP compressée ne peut pas dépasser 256 Mio pour les requêtes
interactions.createsynchrones et en streaming. Lorsqueservice_tierest défini surdeferred(ce qui nécessite quebackgroundetstoresoient définis surtrue), la requête non compressée ne peut pas dépasser 9,75 Mio. - Limite d'URI pour les fichiers Cloud Storage : les requêtes d'interaction du modèle Gemini standard acceptent jusqu'à 100 URI Cloud Storage (
gs://) distincts par requête, y compris les URI reportés des tours de conversation précédents viaprevious_interaction_id. Les interactions avec les agents gérés, les modèles Gemini Omni et les modèles Lyria 3 sont exclus de cette limite de 100 URI. Pour en savoir plus sur les autorisations et la gestion des URI multitours, consultez Accéder aux fichiers Cloud Storage importés. - Limites d'éléments et de jetons multimodaux : les modèles Gemini standards acceptent le même nombre d'éléments par modalité que
generateContent(jusqu'à 3 000 images et PDF combinés, 1 000 fichiers audio, 10 vidéos et jusqu'à 6 500 fichiers multimodaux combinés lorsque des fichiers en texte brut sont inclus), dans la limite de la fenêtre de contexte de 1 048 576 jetons du modèle. Les fichiers Cloud Storage individuels ne peuvent pas dépasser 2 Gio moins 500 Kio, et les URL HTTP ou HTTPS publiques ne peuvent pas dépasser 15 Mio. Pour envoyer plus de 100 fichiers dans une seule requête, transmettez des pièces jointes supplémentaires de manière intégrée dans la limite de la charge utile de la requête ou appelezgenerateContent.
Outils et ancrage compatibles
Les outils intégrés, les fournisseurs d'ancrage et les fonctionnalités de recherche suivants sont compatibles avec les modèles Gemini 3 dans l'API Interactions :
- Ancrage avec la recherche Google et Ancrage Web pour Enterprise : ancre les réponses du modèle avec des informations Web en temps réel issues de la recherche Google ou de l'ancrage Web pour Enterprise.
- Agent Search et moteur RAG sur Gemini Enterprise Agent Platform : ancre les réponses du modèle dans des datastores et des dépôts de documents d'entreprise privés à l'aide d'Agent Search et du moteur RAG.
- Recherche sur le Web Exa : ancre les réponses du modèle avec les résultats de recherche sur le Web de l'API de recherche d'Exa.
- Recherche sur le Web parallèle : ancre les réponses du modèle avec des données Web publiques en temps réel fournies par l'API de recherche sur le Web de Parallel Web Systems.
- Contexte de l'URL : récupère et analyse le contenu des URL Web publiques incluses dans votre prompt.
- Exécution de code : permet au modèle de générer et d'exécuter du code Python dans un environnement sécurisé en bac à sable.
- Utilisation de l'ordinateur : permet d'automatiser les workflows du navigateur et de l'interface utilisateur.
- Appel de fonction : permet aux modèles de se connecter à des outils, des API et des bases de données externes en renvoyant des arguments de fonction structurés.
L'API Interactions est compatible avec l'ancrage Web pour Enterprise et l'ancrage avec la recherche Google. Votre utilisation de ces fonctionnalités est également soumise à leurs Conditions spécifiques.
Facturation
L'utilisation de l'API Interactions est facturée en fonction de la consommation de jetons.
La facturation des requêtes interrompues ou non traitées est gérée comme suit :
- Annulations manuelles : si une interaction est annulée avant la fin (par exemple, en envoyant une demande d'annulation), vous êtes facturé pour les jetons consommés jusqu'au moment de l'annulation.
- Requêtes ayant échoué : si une requête d'interaction échoue en raison d'une erreur système interne ou d'une défaillance du backend, elle ne vous est pas facturée.
Sécurité et conformité
L'API Interactions est compatible avec les contrôles de sécurité, les certifications de conformité et les configurations de point de terminaison suivants :
- Points de terminaison : l'API Interactions est compatible avec le point de terminaison global (
locations/globalsuraiplatform.googleapis.com) et les points de terminaison multirégionauxuseteu(locations/ussuraiplatform.us.rep.googleapis.cometlocations/eusuraiplatform.eu.rep.googleapis.com). Les points de terminaison d'une seule région (commeus-central1oueurope-west1) ne sont pas compatibles. - Résidence des données : l'API Interactions est compatible avec la résidence des données pour le traitement ML (en cours d'utilisation) et les données d'interaction stockées au repos (
store=true) lorsque vous utilisez les points de terminaison multirégionauxuseteu(locations/usetlocations/eu). Les requêtes envoyées au point de terminaisonglobalne fournissent pas de garanties de résidence des données. - Clés de chiffrement gérées par le client (CMEK) : l'API Interactions est compatible avec les CMEK pour les données d'interaction stockées via des profils de diffusion (avec
scopedéfini surINTERACTIONS_API) dans les zones multirégionalesuseteu. Le point de terminaisonglobaln'est pas compatible avec les CMEK. - VPC Service Controls (VPC-SC) : l'API Interactions est compatible avec VPC-SC pour vous aider à sécuriser le périmètre de votre API et à limiter les risques d'exfiltration de données.
- Access Transparency (AXT) : l'API Interactions est compatible avec les journaux AXT pour une visibilité en temps quasi réel lorsque le personnel de Google accède au contenu des interactions stockées.
- Certifications de sécurité et de conformité : l'API Interactions répond aux exigences FedRAMP High dans la limite d'autorisation Google Cloud FedRAMP High. L'API Interactions n'est pas conforme aux exigences du niveau d'impact 5 (IL5) du département de la Défense (DoD) des États-Unis ni à celles de la réglementation américaine sur le commerce international des armes (ITAR, International Traffic in Arms Regulations).
SDK compatibles
Vous pouvez accéder à l'API Interactions à l'aide du SDK Google Gen AI unifié ou d'appels REST directs :
- Python :
google-genaiversion2.3.0ou ultérieure - TypeScript/JavaScript :
@google/genaiversion2.3.0ou ultérieure - Go :
google.golang.org/genai - Java :
com.google.genai:google-genai
Les anciens SDK (google-cloud-aiplatform, @google-cloud/vertexai et google-generativeai) ne sont pas compatibles avec l'API Interactions.
Étapes suivantes
- Installez le SDK Google Gen AI et exécutez votre première requête en suivant le guide du développeur de l'API Interactions.
- Essayez le notebook de démarrage rapide de l'API Interactions.
- Explorez les méthodes et les schémas de ressources dans la documentation de référence de l'API Interactions.
- Découvrez comment interagir avec les agents gérés et utiliser l'agent Gemini Deep Research.