URL context

À l'aide de l'outil de contexte d'URL, vous pouvez fournir à Gemini des URL en tant que contexte supplémentaire pour votre requête. Le modèle peut ensuite récupérer le contenu des URL et l'utiliser pour orienter et façonner sa réponse.

Cet outil est utile pour les tâches suivantes:

  • Extraire des points de données ou des points de discussion clés d'articles
  • Comparer des informations provenant de plusieurs liens
  • Synthétiser des données provenant de plusieurs sources
  • Répondre à des questions basées sur le contenu d'une ou de plusieurs pages spécifiques
  • Analyser du contenu à des fins spécifiques (comme rédiger une description de poste ou créer des questions de test)

Ce guide explique comment utiliser l'outil de contexte d'URL dans l'API Gemini.

Utiliser le contexte de l'URL

Vous pouvez utiliser l'outil de contexte d'URL de deux manières principales : seul ou en conjonction avec la mise à la terre avec la recherche Google.

Contexte de l'URL uniquement

Vous fournissez les URL spécifiques que vous souhaitez que le modèle analyse directement dans votre requête.

Exemples de requêtes :

Summarize this document: YOUR_URLs

Extract the key features from the product description on this page: YOUR_URLs

Ancrage avec la recherche Google et le contexte de l'URL

Vous pouvez également activer à la fois le contexte d'URL et l'ancrage avec la recherche Google. Vous pouvez saisir une requête avec ou sans URL. Le modèle peut d'abord rechercher des informations pertinentes, puis utiliser l'outil de contexte d'URL pour lire le contenu des résultats de recherche afin d'obtenir une compréhension plus approfondie.

Exemples de requêtes :

Give me three day events schedule based on YOUR_URL. Also let me know what needs to taken care of considering weather and commute.

Recommend 3 books for beginners to read to learn more about the latest YOUR_subject.

Exemples de code avec contexte d'URL uniquement

Python

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

client = genai.Client()
model_id = "gemini-2.5-flash-preview-05-20"

url_context_tool = Tool(
    url_context = types.UrlContext
)

response = client.models.generate_content(
    model=model_id,
    contents="Compare recipes from YOUR_URL1 and YOUR_URL2",
    config=GenerateContentConfig(
        tools=[url_context_tool],
        response_modalities=["TEXT"],
    )
)

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({ apiKey: "GEMINI_API_KEY" });

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-2.5-flash-preview-05-20",
    contents: [
        "Compare recipes from YOUR_URL1 and YOUR_URL2",
    ],
    config: {
      tools: [{urlContext: {}}],
    },
  });
  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-preview-05-20:generateContent?key=$GOOGLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "contents": [
          {
              "parts": [
                  {"text": "Compare recipes from YOUR_URL1 and YOUR_URL2"}
              ]
          }
      ],
      "tools": [
          {
              "url_context": {}
          }
      ]
  }' > result.json

cat result.json

Python

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

client = genai.Client()
model_id = "gemini-2.5-flash-preview-05-20"

tools = []
tools.append(Tool(url_context=types.UrlContext))
tools.append(Tool(google_search=types.GoogleSearch))

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,
        response_modalities=["TEXT"],
    )
)

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({ apiKey: "GEMINI_API_KEY" });

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-2.5-flash-preview-05-20",
    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-preview-05-20:generateContent?key=$GOOGLE_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

Pour en savoir plus sur l'ancrage avec la recherche Google, consultez la page Présentation.

Réponse contextuelle

La réponse du modèle sera basée sur le contenu qu'il a récupéré à partir des URL. Si le modèle a récupéré du contenu à partir d'URL, la réponse inclura url_context_metadata. Une telle réponse peut ressembler à ceci (des 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://vertexaisearch.cloud.google.com/grounding-api-redirect/1234567890abcdef",
              "url_retrieval_status": <UrlRetrievalStatus.URL_RETRIEVAL_STATUS_SUCCESS: "URL_RETRIEVAL_STATUS_SUCCESS">
            },
            {
              "retrieved_url": "https://vertexaisearch.cloud.google.com/grounding-api-redirect/abcdef1234567890",
              "url_retrieval_status": <UrlRetrievalStatus.URL_RETRIEVAL_STATUS_SUCCESS: "URL_RETRIEVAL_STATUS_SUCCESS">
            },
            {
              "retrieved_url": "YOUR_URL",
              "url_retrieval_status": <UrlRetrievalStatus.URL_RETRIEVAL_STATUS_SUCCESS: "URL_RETRIEVAL_STATUS_SUCCESS">
            },
            {
              "retrieved_url": "https://vertexaisearch.cloud.google.com/grounding-api-redirect/fedcba0987654321",
              "url_retrieval_status": <UrlRetrievalStatus.URL_RETRIEVAL_STATUS_SUCCESS: "URL_RETRIEVAL_STATUS_SUCCESS">
            }
          ]
        }
    }
}

Modèles compatibles

Limites

  • L'outil peut consommer jusqu'à 20 URL par requête pour l'analyse.
  • Pour de meilleurs résultats pendant la phase expérimentale, utilisez l'outil sur des pages Web standards plutôt que sur des contenus multimédias tels que des vidéos YouTube.
  • Pendant la phase expérimentale, l'outil est sans frais. La facturation sera effectuée ultérieurement.

  • La version expérimentale est soumise aux quotas suivants:

    • 1 500 requêtes par jour et par projet pour les requêtes effectuées via l'API Gemini
    • 100 requêtes par jour et par utilisateur dans Google AI Studio