L'outil de contexte d'URL vous permet de fournir un contexte supplémentaire aux modèles sous 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 :
- Extraire des données : récupérez 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 le code et la documentation : 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 sites Web différents.
Python
from google import genai
from google.genai.types import Tool, GenerateContentConfig
client = genai.Client()
model_id = "gemini-2.5-flash"
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-2.5-flash",
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-2.5-flash: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 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 sert de 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 effectue automatiquement une récupération en direct. Il accède directement à l'URL pour récupérer son contenu en temps réel.
Combiner avec d'autres outils
Vous pouvez combiner l'outil de contexte d'URL avec d'autres outils pour créer des workflows plus efficaces.
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 capacité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 requêtes qui nécessitent à la fois une recherche large 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-2.5-flash"
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-2.5-flash",
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-2.5-flash: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 et l'état de chaque tentative de récupération, ce qui est utile pour la vérification et le débogage.
Voici un exemple de cette partie de la réponse (certaines parties de la réponse ont été omises pour plus 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 documentation de référence de l'API UrlContextMetadata.
Contrôles de sécurité
Le système effectue une vérification de modération du contenu sur l'URL pour confirmer qu'elle respecte les normes de sécurité. Si l'URL que vous avez fournie échoue à ce test, vous obtiendrez 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 requête est comptabilisé dans les jetons d'entrée. Vous pouvez consulter le nombre de jetons pour votre requête et l'utilisation des outils dans l'objet usage_metadata 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
- gemini-2.5-pro
- gemini-2.5-flash
- gemini-2.5-flash-lite
- gemini-live-2.5-flash-preview
- gemini-2.0-flash-live-001
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 celui des liens imbriqués.
- Vérifiez l'accessibilité : assurez-vous que les URL que vous fournissez ne redirigent pas vers des pages qui nécessitent une connexion ou sont soumises à un paywall.
- Utilisez l'URL complète : indiquez l'URL complète, y compris le protocole (par exemple, https://www.google.com au lieu de google.com).
Limites
- Tarifs : le contenu récupéré à partir d'URL est comptabilisé comme des jetons d'entrée. La limite de débit et les tarifs dépendent du modèle utilisé. Pour en savoir plus, consultez les pages Limites de fréquence et Tarifs.
- Limite de demandes : l'outil peut traiter jusqu'à 20 URL par demande.
- Taille du contenu de l'URL : la taille maximale du contenu récupéré à partir d'une seule URL est de 34 Mo.
Types de contenus compatibles et non compatibles
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 contenus suivants ne sont pas acceptés :
- Contenu soumis à un paywall
- Vidéos YouTube (consultez la section Compréhension des vidéos pour savoir comment traiter les URL YouTube)
- Fichiers Google Workspace, comme des documents Google Docs ou des feuilles de calcul
- Fichiers vidéo et audio
Étape suivante
- Pour obtenir d'autres exemples, consultez le cookbook sur le contexte d'URL.