URL context

Lo strumento di contesto dell'URL ti consente di fornire un contesto aggiuntivo ai modelli sotto forma di URL. Se includi URL nella richiesta, il modello accederà ai contenuti di queste pagine (purché non si tratti di un tipo di URL elencato nella sezione Limitazioni) per informare e migliorare la sua risposta.

Lo strumento Contesto URL è utile per attività come le seguenti:

  • Estrai dati: estrai informazioni specifiche come prezzi, nomi o risultati chiave da più URL.
  • Confronta documenti: analizza più report, articoli o PDF per identificare le differenze e monitorare le tendenze.
  • Sintetizza e crea contenuti: combina le informazioni di diversi URL di origine per generare riepiloghi, post del blog o report accurati.
  • Analizza codice e documenti: indica un repository GitHub o una documentazione tecnica per spiegare il codice, generare istruzioni di configurazione o rispondere a domande.

Il seguente esempio mostra come confrontare due ricette di siti web diversi.

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

Come funziona

Lo strumento Contesto URL utilizza un processo di recupero in due passaggi per bilanciare velocità, costi e accesso a dati aggiornati. Quando fornisci un URL, lo strumento tenta innanzitutto di recuperare i contenuti da una cache dell'indice interno. Funge da cache altamente ottimizzata. Se un URL non è disponibile nell'indice (ad esempio, se si tratta di una pagina molto recente), lo strumento esegue automaticamente un recupero in tempo reale. Accede direttamente all'URL per recuperare i contenuti in tempo reale.

Puoi combinare lo strumento di contesto URL con altri strumenti per creare workflow più efficaci.

Quando sono attivi sia il contesto URL sia Grounding with Google Search, il modello può utilizzare le sue funzionalità di ricerca per trovare informazioni pertinenti online e poi utilizzare lo strumento di contesto URL per ottenere una comprensione più approfondita delle pagine che trova. Questo approccio è efficace per i prompt che richiedono sia una ricerca ampia sia un'analisi approfondita di pagine specifiche.

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

Comprendere la risposta

Quando il modello utilizza lo strumento di contesto URL, la risposta include un oggetto url_context_metadata. Questo oggetto elenca gli URL da cui il modello ha recuperato i contenuti e lo stato di ogni tentativo di recupero, il che è utile per la verifica e il debug.

Di seguito è riportato un esempio di questa parte della risposta (alcune parti della risposta sono state omesse per brevità):

{
  "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"
          }
        ]
      }
    }
}

Per informazioni dettagliate su questo oggetto , consulta il riferimento API UrlContextMetadata.

Controlli di sicurezza

Il sistema esegue un controllo della moderazione dei contenuti sull'URL per verificare che soddisfino gli standard di sicurezza. Se l'URL che hai fornito non supera questo controllo, riceverai un url_retrieval_status di URL_RETRIEVAL_STATUS_UNSAFE.

Conteggio dei token

I contenuti recuperati dagli URL specificati nel prompt vengono conteggiati come parte dei token di input. Puoi visualizzare il conteggio dei token per il prompt e l'utilizzo degli strumenti nell'oggetto usage_metadata dell'output del modello. Di seguito è riportato un esempio di output:

'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
  }

Il prezzo per token dipende dal modello utilizzato. Per i dettagli, consulta la pagina Prezzi.

Modelli supportati

Best practice

  • Fornisci URL specifici: per ottenere risultati ottimali, fornisci URL diretti ai contenuti che vuoi che il modello analizzi. Il modello recupererà solo i contenuti dagli URL che fornisci, non i contenuti dei link nidificati.
  • Verifica l'accessibilità: verifica che gli URL forniti non indirizzino a pagine che richiedono l'accesso o che sono protette da paywall.
  • Utilizza l'URL completo: fornisci l'URL completo, incluso il protocollo (ad es. https://www.google.com anziché solo google.com).

Limitazioni

  • Prezzi: i contenuti recuperati dagli URL vengono conteggiati come token di input. Il limite di frequenza e i prezzi si basano sul modello utilizzato. Per ulteriori dettagli, consulta le pagine relative ai limiti di frequenza e ai prezzi.
  • Limite di richieste: lo strumento può elaborare fino a 20 URL per richiesta.
  • Dimensioni dei contenuti URL: la dimensione massima dei contenuti recuperati da un singolo URL è 34 MB.

Tipi di contenuti supportati e non supportati

Lo strumento può estrarre contenuti dagli URL con i seguenti tipi di contenuti:

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

I seguenti tipi di contenuti non sono supportati:

  • Contenuti protetti da paywall
  • Video di YouTube (consulta la sezione Comprensione dei video per scoprire come elaborare gli URL di YouTube)
  • File di Google Workspace come documenti o fogli di lavoro Google
  • File audio e video

Passaggi successivi