URL context

L'outil de contexte d'URL vous permet de fournir un contexte supplémentaire aux modèles sous la forme d'URL. En incluant des URL dans votre requête, le modèle accédera au contenu de ces pages (à condition qu'il ne s'agisse pas d'un type d'URL listé dans la section "Limites") pour informer et améliorer sa réponse.

L'outil de contexte d'URL est utile pour les tâches suivantes, par exemple :

  • Extraire des données : extrayez des informations spécifiques telles que des prix, des noms ou des conclusions clés à partir de plusieurs URL.
  • Comparer des documents : analysez plusieurs rapports, articles ou PDF pour identifier les différences et suivre les tendances.
  • Synthétiser et créer du contenu : combinez des informations provenant de plusieurs URL sources pour générer des résumés, des articles de blog ou des rapports précis.
  • Analyser du code et des documents : pointez vers un dépôt GitHub ou une documentation technique pour expliquer du code, générer des instructions de configuration ou répondre à des questions.

L'exemple suivant montre comment comparer deux recettes provenant de différents sites Web.

Python

from google import genai
from google.genai.types import Tool, GenerateContentConfig

client = genai.Client()
model_id = "gemini-3-flash-preview"

tools = [
  {"url_context": {}},
]

url1 = "https://www.foodnetwork.com/recipes/ina-garten/perfect-roast-chicken-recipe-1940592"
url2 = "https://www.allrecipes.com/recipe/21151/simple-whole-roast-chicken/"

response = client.models.generate_content(
    model=model_id,
    contents=f"Compare the ingredients and cooking times from the recipes at {url1} and {url2}",
    config=GenerateContentConfig(
        tools=tools,
    )
)

for each in response.candidates[0].content.parts:
    print(each.text)

# For verification, you can inspect the metadata to see which URLs the model retrieved
print(response.candidates[0].url_context_metadata)

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-3-flash-preview",
    contents: [
        "Compare the ingredients and cooking times from the recipes at https://www.foodnetwork.com/recipes/ina-garten/perfect-roast-chicken-recipe-1940592 and https://www.allrecipes.com/recipe/21151/simple-whole-roast-chicken/",
    ],
    config: {
      tools: [{urlContext: {}}],
    },
  });
  console.log(response.text);

  // For verification, you can inspect the metadata to see which URLs the model retrieved
  console.log(response.candidates[0].urlContextMetadata)
}

await main();

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "contents": [
          {
              "parts": [
                  {"text": "Compare the ingredients and cooking times from the recipes at https://www.foodnetwork.com/recipes/ina-garten/perfect-roast-chicken-recipe-1940592 and https://www.allrecipes.com/recipe/21151/simple-whole-roast-chicken/"}
              ]
          }
      ],
      "tools": [
          {
              "url_context": {}
          }
      ]
  }' > result.json

cat result.json

Fonctionnement

L'outil de contexte d'URL utilise un processus de récupération en deux étapes pour équilibrer la vitesse, le coût et l'accès à des données récentes. Lorsque vous fournissez une URL, l'outil tente d'abord d'extraire le contenu d'un cache d'index interne. Il s'agit d'un cache hautement optimisé. Si une URL n'est pas disponible dans l'index (par exemple, s'il s'agit d'une page très récente), l'outil revient automatiquement à une extraction en direct. Il accède directement à l'URL pour récupérer son contenu en temps réel.

Vous pouvez combiner l'outil de contexte d'URL avec d'autres outils pour créer des workflows plus puissants.

Les modèles Gemini 3 sont compatibles avec la combinaison d'outils intégrés (comme le contexte d'URL) et d'outils personnalisés (appel de fonction). Pour en savoir plus, consultez la page Combinaisons d'outils.

Lorsque le contexte d'URL et l'ancrage avec la recherche Google sont activés, le modèle peut utiliser ses fonctionnalités de recherche pour trouver des informations pertinentes en ligne, puis utiliser l'outil de contexte d'URL pour mieux comprendre les pages qu'il trouve. Cette approche est efficace pour les prompts qui nécessitent à la fois une recherche étendue et une analyse approfondie de pages spécifiques.

Python

from google import genai
from google.genai.types import Tool, GenerateContentConfig, GoogleSearch, UrlContext

client = genai.Client()
model_id = "gemini-3-flash-preview"

tools = [
      {"url_context": {}},
      {"google_search": {}}
  ]

response = client.models.generate_content(
    model=model_id,
    contents="Give me three day events schedule based on YOUR_URL. Also let me know what needs to taken care of considering weather and commute.",
    config=GenerateContentConfig(
        tools=tools,
    )
)

for each in response.candidates[0].content.parts:
    print(each.text)
# get URLs retrieved for context
print(response.candidates[0].url_context_metadata)

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-3-flash-preview",
    contents: [
        "Give me three day events schedule based on YOUR_URL. Also let me know what needs to taken care of considering weather and commute.",
    ],
    config: {
      tools: [
        {urlContext: {}},
        {googleSearch: {}}
        ],
    },
  });
  console.log(response.text);
  // To get URLs retrieved for context
  console.log(response.candidates[0].urlContextMetadata)
}

await main();

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "contents": [
          {
              "parts": [
                  {"text": "Give me three day events schedule based on YOUR_URL. Also let me know what needs to taken care of considering weather and commute."}
              ]
          }
      ],
      "tools": [
          {
              "url_context": {}
          },
          {
              "google_search": {}
          }
      ]
  }' > result.json

cat result.json

Comprendre la réponse

Lorsque le modèle utilise l'outil de contexte d'URL, la réponse inclut un objet url_context_metadata. Cet objet liste les URL à partir desquelles le modèle a récupéré du contenu, ainsi que l'état de chaque tentative de récupération, ce qui est utile pour la validation et le débogage.

Voici un exemple de cette partie de la réponse (certaines parties de la réponse ont été omises par souci de concision) :

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "... \n"
          }
        ],
        "role": "model"
      },
      ...
      "url_context_metadata": {
        "url_metadata": [
          {
            "retrieved_url": "https://www.foodnetwork.com/recipes/ina-garten/perfect-roast-chicken-recipe-1940592",
            "url_retrieval_status": "URL_RETRIEVAL_STATUS_SUCCESS"
          },
          {
            "retrieved_url": "https://www.allrecipes.com/recipe/21151/simple-whole-roast-chicken/",
            "url_retrieval_status": "URL_RETRIEVAL_STATUS_SUCCESS"
          }
        ]
      }
    }
  ]
}

Pour en savoir plus sur cet objet , consultez la UrlContextMetadata documentation de référence de l'API.

Vérifications de sécurité

Le système effectue une vérification de modération du contenu sur l'URL pour s'assurer qu'elle respecte les normes de sécurité. Si l'URL que vous avez fournie échoue à cette vérification, vous recevrez un url_retrieval_status de URL_RETRIEVAL_STATUS_UNSAFE.

Nombre de jetons

Le contenu récupéré à partir des URL que vous spécifiez dans votre prompt est comptabilisé dans les jetons d'entrée. Vous pouvez consulter le nombre de jetons pour votre prompt et l'utilisation des outils dans l'usage_metadata objet de la sortie du modèle. Voici un exemple de résultat :

'usage_metadata': {
  'candidates_token_count': 45,
  'prompt_token_count': 27,
  'prompt_tokens_details': [{'modality': <MediaModality.TEXT: 'TEXT'>,
    'token_count': 27}],
  'thoughts_token_count': 31,
  'tool_use_prompt_token_count': 10309,
  'tool_use_prompt_tokens_details': [{'modality': <MediaModality.TEXT: 'TEXT'>,
    'token_count': 10309}],
  'total_token_count': 10412
  }

Le prix par jeton dépend du modèle utilisé. Pour en savoir plus, consultez la page Tarifs.

Modèles compatibles

Modèle Contexte d'URL
Preview Gemini 3.1 Pro ✔️
Preview Gemini 3.1 Flash-Lite ✔️
Preview Gemini 3 Flash ✔️
Gemini 2.5 Pro ✔️
Gemini 2.5 Flash ✔️
Gemini 2.5 Flash-Lite ✔️

Bonnes pratiques

  • Fournissez des URL spécifiques : pour obtenir les meilleurs résultats, fournissez des URL directes vers le contenu que vous souhaitez que le modèle analyse. Le modèle ne récupérera le contenu que des URL que vous fournissez, et non celui des liens imbriqués.
  • Vérifiez l'accessibilité : vérifiez que les URL que vous fournissez ne mènent pas à des pages qui nécessitent des identifiants de connexion ou qui sont soumises à un paywall.
  • Utilisez l'URL complète : fournissez l'URL complète, y compris le protocole (par exemple, https://www.google.com au lieu de google.com).

Limites

  • Appel de fonction : l'utilisation d'outils (contexte d'URL, ancrage avec la recherche Google, etc.) avec l'appel de fonction n'est actuellement pas prise en charge.
  • Limite de requêtes : l'outil peut traiter jusqu'à 20 URL par requête.
  • Taille du contenu de l'URL : la taille maximale du contenu récupéré à partir d'une seule URL est de 34 Mo.
  • Accessibilité publique : les URL doivent être accessibles au public sur le Web. Les adresses localhost (par exemple, localhost, 127.0.0.1), les réseaux privés et les services de tunneling (par exemple, ngrok, pinggy) ne sont pas pris en charge.
  • API Gemini uniquement : le contexte d'URL n'est disponible que dans l'API Gemini, et non via Gemini Enterprise Agent Platform.

Types de contenu pris en charge et non pris en charge

L'outil peut extraire du contenu à partir d'URL avec les types de contenu suivants :

  • Texte (text/html, application/json, text/plain, text/xml, text/css, text/javascript , text/csv, text/rtf)
  • Image (image/png, image/jpeg, image/bmp, image/webp)
  • PDF (application/pdf)

Les types de contenu suivants ne sont pas pris en charge :

  • Contenu soumis à un paywall
  • Vidéos YouTube (consultez la section Comprendre les vidéos pour savoir comment traiter les URL YouTube)
  • Fichiers Google Workspace tels que des documents ou des feuilles de calcul Google
  • Fichiers audio et vidéo

Étape suivante