Aller au contenu

Moteurs IA

Le grounding de l'API Gemini avec Google Search, champ par champ

L'outil google_search renvoie les requêtes lancées, des annotations url_citation et un bloc Search Suggestions, à 14 $ pour 1 000 recherches après 5 000 offertes.

Trois disques plats se relient par un anneau bleu à un cube isométrique sur fond clair

Consultant SEO, et plus récemment GEO, chez MentionBox

Le grounding avec Google Search est un outil que l'on déclare dans un appel à l'API Gemini. Le modèle lit votre prompt, décide seul si une recherche améliorerait la réponse, rédige et lance ses propres requêtes Google, puis renvoie une réponse unique de synthèse. Le guide de Google détaille ce qui accompagne cette réponse : une étape google_search_call qui porte les queries exécutées, une étape google_search_result qui porte un bloc HTML search_suggestions destiné à votre interface, et le texte lui-même, muni d'annotations url_citation avec un url, un title, un start_index et un end_index. Sur Gemini 3 et les modèles suivants, le projet paie chaque recherche que le modèle choisit de lancer, 14 $ pour 1 000 requêtes de recherche après 5 000 offertes par mois, sous un plafond par défaut de 1 500 requêtes par jour. Trois choses ne reviennent pas : l'adresse réelle de l'éditeur, le moindre indicateur de rang ou de part, et le droit de conserver les liens sous forme d'index.

Cette page s'adresse au développeur qui a branché l'outil sur une application Gemini et trouve les citations inexploitables, et à celui qui espérait mesurer la visibilité d'une marque dans Gemini avec une clé officielle de Google. Elle couvre la requête, chaque champ de la réponse dans les deux formes de l'API, les quatre choses que l'outil garde pour lui, ce que les conditions autorisent à stocker, le calcul d'un mois d'appels, et le moment où le grounding cesse d'être le bon instrument.

À quoi ressemble une requête enrichie

La forme actuelle tient en un POST vers le point de terminaison Interactions, l'outil étant déclaré par son type, sans autre paramètre :

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "best AI visibility API for an agency",
    "tools": [{"type": "google_search"}]
  }'

Le même appel en Python tient en trois lignes avec le client google-genai, client.interactions.create() avec model, input et le même tableau tools. Le guide de Google cite Gemini 4 Argon, la famille Gemini 3.x, Gemini 2.5 Pro, Flash et Flash-Lite ainsi que Gemini 2.0 Flash parmi les modèles pris en charge, et précise que les modèles plus anciens utilisent un outil google_search_retrieval au lieu de google_search. C'est dans cet ancien outil que vivait le réglage de récupération dynamique : quand Google a ouvert le grounding à l'API Gemini en décembre 2024, il expliquait qu'un score de prédiction entre 0 et 1 décide si un prompt a besoin d'être enrichi, avec un seuil par défaut de 0,3 que le développeur pouvait déplacer.

Rien, dans l'outil déclaré, ne fixe un pays, une langue ou un filtre de domaine. C'est le premier manque pratique face à l'équivalent côté OpenAI, dont l'outil de recherche web documente un objet user_location et un paramètre filters qui accepte jusqu'à 100 domaines autorisés ou bloqués.

La réponse, champ par champ

Deux formes de réponse circulent, et une intégration écrite pour l'une ne lit pas l'autre. L'API Interactions renvoie des étapes et des annotations ; le point de terminaison generateContent, que Google étiquette désormais comme hérité, renvoie un objet groundingMetadata sur le candidat.

DonnéeAPI InteractionsgenerateContentÀ quoi elle sert
Les requêtes lancées par le modèlegoogle_search_call.queriesgroundingMetadata.webSearchQueriesvoir le fan-out derrière un prompt, et compter ce qui est facturé
Les pages citéesurl et title sur chaque annotation url_citationgroundingChunks[].web.uri et .web.titlela liste des sources, sous forme de liens de redirection
Le lien entre réponse et sourcestart_index et end_index sur chaque annotationgroundingSupports[].segment avec startIndex, endIndex, text, et groundingChunkIndicesconstruire des citations en ligne dans votre interface
Les Search Suggestionsgoogle_search_result.search_suggestionsgroundingMetadata.searchEntryPoint.renderedContentle HTML et le CSS que Google impose d'afficher
Le comptage des jetonsusage avec total_input_tokens, total_output_tokens, total_tool_use_tokenshors de groundingMetadatala seconde moitié de la facture

Noms de champs relevés dans le guide de grounding de Google, sa page generateContent héritée et la référence de l'API Interactions, le 30 octobre 2026.

Le tableau groundingSupports mérite une lecture attentive : c'est le seul endroit où l'API dit quelle phrase repose sur quelle source. Google le présente comme le tableau des blocs qui relient le texte de la réponse aux sources de groundingChunks, chacun rattachant un segment de texte à un ou plusieurs groundingChunkIndices. Voici la forme que montre son propre exemple, avec notre prompt à la place de sa question de football :

{
  "groundingMetadata": {
    "webSearchQueries": [
      "best AI visibility API for agencies",
      "AI visibility API resale white label"
    ],
    "searchEntryPoint": { "renderedContent": "<!-- HTML et CSS des Search Suggestions -->" },
    "groundingChunks": [
      { "web": { "uri": "https://vertexaisearch.cloud.google.com/grounding-api-redirect/...", "title": "example.com" } }
    ],
    "groundingSupports": [
      {
        "segment": { "startIndex": 0, "endIndex": 85, "text": "..." },
        "groundingChunkIndices": [0]
      }
    ]
  }
}

Une réponse vous donne donc une liste de requêtes, une liste de sources et une carte phrase par phrase entre les deux. Pour une application qui affiche des citations à un lecteur, le travail est fait. Pour un comptage par marque ou par domaine, il commence.

Les quatre choses que le grounding ne renvoie pas

L'adresse de l'éditeur. Dans l'exemple de réponse publié par Google, l'uri de chaque bloc de grounding pointe vers vertexaisearch.cloud.google.com et le title se réduit au domaine nu, aljazeera.com dans son cas. Le domaine est donc lisible, l'adresse de la page ne l'est pas, et l'atteindre suppose de suivre la redirection. Une demande d'évolution réclamant les adresses réelles traîne sur le forum développeurs de Google depuis 2026 sans réponse publiée, les développeurs du fil décrivant les deux mêmes symptômes : une redirection dans web.uri, un web.title limité au domaine.

Le moindre indicateur de rang ou de part. Les annotations disent sur quelle source s'appuie chaque segment. Elles ne disent pas où se trouve un nom de marque dans la réponse, combien de fois il revient sur plusieurs exécutions, ni quels concurrents sont nommés à côté. Ce calcul vous revient, et les conditions de la section suivante décident si vous avez le droit de l'écrire.

Un réglage de pays ou de langue. L'outil est déclaré par son seul type dans tous les exemples que publie Google. L'annonce décrit le grounding comme fonctionnant dans toutes les langues disponibles, ce qui relève de la capacité et non d'un paramètre que l'on fixe. Si la mesure attendue dépend du pays, la forme de la requête ne l'exprime pas.

La garantie qu'une recherche a eu lieu. Le guide indique que le modèle détermine lui-même si une recherche Google améliorerait la réponse, ce qui laisse une question d'actualité revenir fluide, assurée et périmée. L'absence d'étape google_search_call, ou de webSearchQueries dans la forme héritée, est le seul signal disponible.

Une cinquième absence a sa place ici, parce qu'elle fonde la lecture la plus courante de cet outil. Une réponse Gemini enrichie n'est pas la réponse d'AI Overviews ou d'AI Mode qu'un internaute lit dans Google Search. Ce sont des fonctions de Search, documentées pour les éditeurs dans AI features and your website, et aucune API de Google n'en renvoie le texte. Notre guide sur la collecte des réponses d'AI Mode par API traite cette voie, et la même séparation existe chez OpenAI, détaillée dans l'outil de recherche web face aux réponses de ChatGPT.

Ce que les conditions autorisent à garder

La plupart des pages sur cet outil s'arrêtent à la forme de la réponse. Les conditions de l'API Gemini comportent une section dédiée au grounding, et elle régit ce qu'un projet peut légalement faire de tout ce qui précède.

  • L'affichage est lié à un seul lecteur. Les résultats enrichis ne sont affichés, avec les Search Suggestions associées, qu'à l'utilisateur final qui a envoyé le prompt, dans des applications que vous détenez et exploitez.
  • Cinq suggestions, non modifiées. Cinq Search Suggestions au maximum peuvent accompagner les résultats finaux, et vous ne modifiez pas les résultats enrichis ni les Search Suggestions, et n'y intercalez aucun autre contenu. Rien ne peut s'interposer entre un lien et sa page de destination.
  • Deux ans, trois usages. Le texte enrichi peut être conservé deux ans au maximum, et seulement pour évaluer la façon dont il est affiché, tenir l'historique de conversation d'un utilisateur, ou le resoumettre temporairement afin d'obtenir un résultat affiné, les Search Suggestions étant affichées à chaque fois.
  • Aucune mise en cache pour autre chose. Les conditions interdisent de mettre en cache, d'encadrer, de syndiquer, de revendre, d'analyser ou d'entraîner sur les résultats, ainsi que de collecter les liens ou d'utiliser des moyens automatisés pour en construire un index.
  • Google en garde sa copie trente jours. Les prompts, les informations de contexte et la sortie sont conservés trente jours, pour produire les résultats enrichis et pour le débogage et les tests.

Ce que coûte un mois de grounding

La facture a deux moitiés, et la seconde s'oublie vite : les pages trouvées arrivent dans le modèle sous forme de jetons, facturés au tarif du modèle.

ConfigurationCe que facture Google
Gemini 3 et suivants, google_search14 $ pour 1 000 requêtes de recherche, après 5 000 offertes par mois et partagées entre ces modèles ; chaque requête lancée compte à part
Gemini 2.5 et antérieurs, google_search35 $ pour 1 000 prompts enrichis, avec 1 500 requêtes offertes par jour partagées entre Flash et Flash-Lite
Jetons sur Gemini 3.8 Flash0,75 $ par million en entrée, 3,75 $ par million en sortie
Jetons sur Gemini 2.5 Flash0,30 $ par million en entrée, 2,50 $ par million en sortie
Jetons sur Gemini 2.5 Pro1,25 $ par million en entrée, 10,00 $ par million en sortie
url_context à côté de la recherchecontenu des pages récupérées facturé en jetons d'entrée, jusqu'à 20 URL par requête et 34 Mo par URL

Tarifs relevés sur la page de prix de Google, sa page de limites de débit et son guide URL context, le 30 octobre 2026.

Le passage de la facturation au prompt à la facturation à la requête a un point d'équilibre calculable : 35 $ divisés par 14 $ font 2,5, donc un prompt qui déclenche moins de deux recherches et demie revient moins cher sur Gemini 3 et les modèles suivants, tandis qu'un prompt de recherche approfondie qui se déploie en huit requêtes y coûte 0,112 $ contre 0,035 $ forfaitaires sur Gemini 2.5. L'exemple documenté par Google découpe une courte question factuelle en deux requêtes, ce qui représente le bas de la fourchette. Les prompts comparatifs, ceux qui intéressent vraiment une marque, se situent en haut, et rien dans l'API ne plafonne le compte.

Un mois chiffré, sur Gemini 3.8 Flash, pour 200 prompts lancés une fois par semaine : 200 × 4,3, soit environ 860 prompts. À deux recherches chacun, 1 720 requêtes de recherche, donc rien de facturé le premier mois face aux 5 000 offertes, et 24,08 $ une fois l'allocation consommée. Google ne publie aucune moyenne du volume de pages qu'une recherche transmet au modèle : prenons 8 000 jetons en entrée et 500 en sortie par réponse comme hypothèse de travail, et le volet jetons revient à 0,008 $ par réponse, environ 6,80 $ sur le mois. La ligne de recherche et la ligne de jetons tombent dans le même ordre de grandeur, et une grille tarifaire seule ne le dit pas. Notre décryptage du fan-out dans la recherche IA explique pourquoi ce nombre de recherches varie autant d'un type de question à l'autre.

Cinq erreurs qui cassent une intégration enrichie

  1. Faire confiance à la liste de citations sans la résoudre. Stockez le domaine issu de web.title et la redirection issue de web.uri dans deux colonnes distinctes, et ne résolvez la redirection qu'au moment où la page est vraiment nécessaire, dans les limites des conditions.
  2. Supposer que la recherche a eu lieu. Enregistrez la présence de l'étape google_search_call avec chaque réponse. Sans cette colonne, un mois de journaux mélange réponses enrichies et réponses de mémoire, et aucune analyse ultérieure ne les sépare.
  3. Jeter les Search Suggestions. Le HTML de renderedContent n'est pas un ornement. S'en débarrasser place l'application hors des conditions qui l'autorisent.
  4. Dimensionner un budget sur les prompts. Sur Gemini 3 et les modèles suivants, l'unité facturée est la requête que le modèle invente, pas la question que vous envoyez. Journalisez la longueur de webSearchQueries à chaque appel et lisez la distribution réelle avant de vous engager sur un volume.
  5. Mélanger les deux formes de réponse dans une même table. groundingChunks et les annotations url_citation portent des données qui se recouvrent sous des noms différents. Normalisez à l'entrée, sinon une migration recomptera un an de lignes.

Où s'arrête le grounding, et ce qui prend le relais

Le grounding avec Google Search est un outil de qualité de réponse, pour une application que vous détenez. Il fait citer de vraies pages à une fonction propulsée par Gemini, et il le fait bien, avec une carte phrase par phrase que peu de moteurs fournissent. Mesurer ce que les moteurs racontent aux acheteurs est un autre exercice : les mêmes prompts relancés sur plusieurs moteurs, des noms de marque rapprochés par alias, des positions et une part de voix calculées à chaque exécution, et une licence qui autorise à stocker les résultats et à les montrer à un client.

Cette dernière clause sépare les deux catégories. Comme exemple concret de la seconde, API for GEO exécute une liste de prompts stockée nativement sur chaque moteur, dans le pays et la langue demandés, et renvoie la réponse avec les URL citées classées par catégorie, les mentions de marque, la position, la part de voix, le sentiment et les questions de fan-out posées par le moteur, à 13 $ pour 1 000 réponses et jusqu'à 7 $ à son plus gros palier, la revente et la marque blanche étant publiées comme un usage prévu. Gemini figure parmi ses moteurs, confirmé par notre test en conditions réelles du 26 octobre 2026 et non documenté sur apiforgeo.com, comme ses webhooks, sa spécification OpenAPI et ses SDK officiels. MentionBox, qui édite ce site, a un lien commercial avec API for GEO.

Le grounding n'est pas non plus la seule source que Google branche sur un modèle Gemini. La vue d'ensemble du grounding sur Gemini Enterprise Agent Platform liste Google Maps, Agent Search, Elasticsearch, votre propre API de recherche et des moteurs de recherche web tiers parmi les options, chacune avec ses conditions. Si le blocage vient de la clause et non des noms de champs, changer de source de grounding est un chemin plus court que changer de modèle.

Questions fréquentes

Combien coûte le grounding de l'API Gemini avec Google Search ?

Sur Gemini 3 et les modèles suivants, le projet paie chaque requête de recherche que le modèle décide de lancer, à 14 $ pour 1 000 après 5 000 offertes par mois et partagées entre ces modèles. Gemini 2.5 et les modèles antérieurs sont facturés au prompt enrichi, à 35 $ pour 1 000, avec 1 500 requêtes offertes par jour partagées entre Flash et Flash-Lite. Les pages que la recherche transmet au modèle se paient en plus, en jetons, au tarif du modèle : 0,75 $ par million en entrée et 3,75 $ par million en sortie sur Gemini 3.8 Flash. Tarifs relevés sur la page de prix de Google le 30 octobre 2026.

L'API Gemini renvoie-t-elle les vraies adresses des pages citées ?

Pas dans les métadonnées de grounding. L'exemple de réponse publié par Google montre chaque source sous la forme d'un `web.uri` qui pointe vers `vertexaisearch.cloud.google.com`, avec un `web.title` réduit au domaine, du type `aljazeera.com` : l'adresse de l'éditeur s'obtient en suivant la redirection, pas en lisant la réponse. Une demande d'évolution réclamant les adresses réelles est ouverte depuis 2026 sur le forum développeurs de Google, sans réponse publiée. Prévoyez une étape de résolution, et lisez les conditions avant de stocker ce que vous récupérez.

Comment savoir si le modèle a réellement cherché ?

En cherchant l'étape de recherche dans la réponse. Une réponse enrichie porte un `google_search_call` contenant les requêtes lancées dans l'API Interactions, ou un tableau `groundingMetadata.webSearchQueries` dans la forme generateContent ; une réponse qui n'a ni l'un ni l'autre vient des poids du modèle. Le guide de Google présente la décision comme celle du modèle, et la référence de l'API Interactions liste `tool_choice.mode` avec `auto`, `any`, `none` et `validated`, plus une liste `allowed_tools`, comme leviers sur l'usage des outils. Enregistrez la présence ou l'absence de cette étape à côté de chaque réponse conservée.

Peut-on suivre la visibilité de sa marque dans Gemini avec le grounding ?

Les conditions ne le permettent pas. Les conditions de l'API Gemini prévoient que les résultats enrichis ne sont affichés, avec leurs Search Suggestions, qu'à l'utilisateur final qui a envoyé le prompt, limitent l'affichage à cinq Search Suggestions, autorisent la conservation du texte pendant deux ans au maximum pour trois usages nommés, et interdisent la mise en cache, la syndication, la revente, l'analyse et l'entraînement, ainsi que la collecte des liens et toute construction automatisée d'un index. Mesurer un moteur suppose des exécutions répétées, un comptage par marque et une licence qui autorise le stockage : un autre produit qu'un outil de qualité de réponse.

Le grounding équivaut-il à AI Overviews ou à AI Mode ?

Non. Un appel enrichi répond avec le modèle Gemini que vous avez nommé, Google Search attaché comme outil, tandis qu'AI Overviews et AI Mode sont des fonctions de Google Search, documentées pour les éditeurs de sites dans la page sur les fonctionnalités IA. Les deux chaînes traitent des prompts différents, donc le texte et la liste des sources diffèrent, et Google ne publie aucune API qui renvoie la réponse d'AI Mode. Si vous stockez les deux, gardez-les dans deux colonnes séparées.

Quelles limites de débit s'appliquent au grounding ?

La page des limites de Google indique que le grounding avec Google Search sur Gemini 3 et les modèles suivants porte un plafond par défaut de 1 500 requêtes par jour et par projet sur l'API Gemini Developer, les hausses se demandant depuis AI Studio. Sur Gemini 2.5 et les modèles antérieurs, l'allocation gratuite est aussi de 1 500 requêtes par jour, partagée entre Flash et Flash-Lite. Une tâche nocturne de 200 prompts qui se déploient chacun en cinq recherches atteint ce plafond à 1 000 requêtes de recherche : dimensionnez le planning sur les recherches, pas sur les prompts.