Contexte de l'URL

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

# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()

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

interaction = client.interactions.create(
    model="gemini-3.5-flash",
    input=f"Compare the ingredients and cooking times from the recipes at {url1} and {url2}",
    tools=[{"type": "url_context"}]
)

# Print the model's text response and its source annotations
for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
                if content_block.annotations:
                    print("\nSources:")
                    for annotation in content_block.annotations:
                        if annotation.type == "url_citation":
                            print(f"  - {annotation.title}: {annotation.url}")

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

async function main() {
  const interaction = await client.interactions.create({
    model: "gemini-3.5-flash",
    input: "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: [{ type: "url_context" }]
  });

  // Print the model's text response and its source annotations
  for (const step of interaction.steps) {
    if (step.type === 'model_output') {
      for (const contentBlock of step.content) {
        if (contentBlock.type === 'text') {
          console.log(contentBlock.text);
          if (contentBlock.annotations) {
            console.log("\nSources:");
            for (const annotation of contentBlock.annotations) {
              if (annotation.type === 'url_citation') {
                console.log(`  - ${annotation.title}: ${annotation.url}`);
              }
            }
          }
        }
      }
    }
  }
}

await main();

# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
      "model": "gemini-3.5-flash",
      "input": "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": [{"type": "url_context"}]
  }'

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

Combinaison avec d'autres outils

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 sur les combinaisons d'outils.

Ancrage avec la recherche

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 invites qui nécessitent à la fois une recherche étendue et une analyse approfondie de pages spécifiques.

# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.5-flash",
    input="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=[
        {"type": "url_context"},
        {"type": "google_search"}
    ]
)

for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

async function main() {
  const interaction = await client.interactions.create({
    model: "gemini-3.5-flash",
    input: "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: [
      { type: "url_context" },
      { type: "google_search" }
    ]
  });

  for (const step of interaction.steps) {
    if (step.type === 'model_output') {
      for (const contentBlock of step.content) {
        if (contentBlock.type === 'text') console.log(contentBlock.text);
      }
    }
  }
}

await main();

# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
      "model": "gemini-3.5-flash",
      "input": "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": [
          {"type": "url_context"},
          {"type": "google_search"}
      ]
  }'

Comprendre la réponse

Lorsque le modèle utilise l'outil de contexte d'URL, sa réponse textuelle inclut des annotations url_citation intégrées dans le bloc de contenu textuel. Chaque annotation associe un segment du texte de réponse (via start_index et end_index) à l'URL source à partir de laquelle il a été dérivé. Il s'agit du principal moyen de faire apparaître des citations dans votre application. Pour savoir comment les extraire, consultez le principal exemple ci-dessus.

La réponse inclut également une étape url_context_result avec des métadonnées sur chaque tentative de récupération d'URL (état, URL récupérée). Cela est principalement utile pour le débogage.

Vérifications de sécurité

Le système effectue une vérification de modération du contenu sur les URL pour s'assurer qu'elles respectent les normes de sécurité. Si une URL échoue à cette vérification, l'étape correspondante url_context_result affiche un status de "unsafe".

Nombre de jetons

Le contenu récupéré à partir des URL que vous spécifiez dans votre invite est comptabilisé dans les jetons d'entrée. Vous pouvez voir le nombre de jetons dans l'objet usage de l'interaction. Voici un exemple :

'usage': {
  'output_tokens': 45,
  'input_tokens': 27,
  'input_tokens_details': [{'modality': 'TEXT', 'token_count': 27}],
  'thoughts_tokens': 31,
  'tool_use_input_tokens': 10309,
  'tool_use_input_tokens_details': [{'modality': 'TEXT', 'token_count': 10309}],
  'total_tokens': 10412
}

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

Modèles compatibles

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 que le contenu des URL que vous fournissez, et non le contenu 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 une 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

• 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 acceptés.
• 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 compatibles et non compatibles

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

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

Les types de contenu suivants ne sont pas acceptés :

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