Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Contesto URL

Puoi utilizzare lo strumento Contesto URL per fornire a Gemini gli URL come contesto aggiuntivo per il tuo prompt. Il modello può quindi recuperare i contenuti dagli URL e utilizzarli per informare e dare forma alla sua risposta.

Questo strumento è utile per attività come:

Estrazione di punti dati o argomenti chiave dagli articoli
Confrontare le informazioni di più link
Sintetizzare i dati provenienti da più fonti
Rispondere alle domande in base ai contenuti di una o più pagine specifiche
Analizzare i contenuti per scopi specifici (ad esempio, scrivere una descrizione di un lavoro o creare domande per un test)

Tieni presente che l'indice utilizzato per estrarre i dati potrebbe non essere necessariamente aggiornato, pertanto alcune informazioni potrebbero essere obsolete.

Questa guida spiega come utilizzare lo strumento di contesto degli URL nell'API Gemini.

Modelli supportati

I seguenti modelli supportano il contesto URL:

Fai clic per espandere i modelli supportati

Usa il contesto URL

Puoi utilizzare lo strumento di contesto degli URL in due modi principali: da solo o in combinazione con il grounding con la Ricerca Google.

Solo contesto URL

Puoi fornire URL specifici che vuoi che il modello analizzi direttamente nel prompt:

Summarize this document: YOUR_URLs

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

Python

API GenerateContent

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

client = genai.Client(http_options=HttpOptions(api_version="v1"))
model_id = "gemini-3.5-flash"

url_context_tool = Tool(
    url_context = 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)

API Interactions

from google import genai

client = genai.Client(
    enterprise=True,
    project="GOOGLE_CLOUD_PROJECT",
    location="global",
)

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Compare recipes from YOUR_URL1 and YOUR_URL2",
    tools=[{"type": "url_context"}],
)

print(interaction.output_text)

# Get URLs retrieved for context
for step in interaction.steps:
    if step.type == "url_context_result":
        for res in step.result:
            print(f"URL: {res.url} (Status: {res.status})")

JavaScript

API GenerateContent

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

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

const ai = new GoogleGenAI({
  vertexai: true,
  project: process.env.GOOGLE_CLOUD_PROJECT,
  location: process.env.GOOGLE_CLOUD_LOCATION,
  apiVersion: 'v1',
});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-3.5-flash",
    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();

API Interactions

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

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

const ai = new GoogleGenAI({
  enterprise: true,
  project: process.env.GOOGLE_CLOUD_PROJECT,
  location: process.env.GOOGLE_CLOUD_LOCATION,
});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Compare recipes from YOUR_URL1 and YOUR_URL2",
    tools: [{ type: "url_context" }],
  });

  console.log(interaction.output_text);

  for (const step of interaction.steps) {
    if (step.type === "url_context_result") {
      console.log(step.result);
    }
  }
}

await main();

REST

API GenerateContent

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

GOOGLE_CLOUD_PROJECT: il tuo ID progetto
YOUR_URL1: il primo URL da cui recuperare il contesto.
YOUR_URL2: il secondo URL da cui recuperare il contesto.

Metodo HTTP e URL:

POST https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/publishers/google/models/gemini-3.5-flash:generateContent

Corpo JSON della richiesta:

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Compare recipes from YOUR_URL1 and YOUR_URL2"
        }
      ]
    }
  ],
  "tools": [
    {
      "url_context": {}
    }
  ]
}

Per inviare la richiesta, scegli una di queste opzioni:

curl

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che consente di accedere automaticamente all'interfaccia a riga di comando gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/publishers/google/models/gemini-3.5-flash:generateContent"

PowerShell

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/publishers/google/models/gemini-3.5-flash:generateContent" | Select-Object -Expand Content

API Interactions

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

GOOGLE_CLOUD_PROJECT: il tuo ID progetto
YOUR_URL1: il primo URL da cui recuperare il contesto.
YOUR_URL2: il secondo URL da cui recuperare il contesto.

Metodo HTTP e URL:

POST https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/interactions

Corpo JSON della richiesta:

{
  "model": "gemini-3.8-flash",
  "input": [
    {
      "type": "user_input",
      "content": [
        {
          "type": "text",
          "text": "Compare recipes from YOUR_URL1 and YOUR_URL2"
        }
      ]
    }
  ],
  "tools": [
    {
      "type": "url_context"
    }
  ]
}

Per inviare la richiesta, scegli una di queste opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/interactions"

PowerShell

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/interactions" | Select-Object -Expand Content

Grounding con la Ricerca Google con contesto dell'URL

Puoi anche attivare sia il contesto dell'URL che il grounding con la Ricerca Google, utilizzando i prompt con o senza URL. Il modello potrebbe prima cercare informazioni pertinenti e poi utilizzare lo strumento di contesto dell'URL per leggere i contenuti dei risultati di ricerca per una comprensione più approfondita.

Questa funzionalità è sperimentale e disponibile nella versione API v1beta1.

Prompt di esempio:

Give me a three day event 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.

Python

API GenerateContent

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

client = genai.Client(http_options=HttpOptions(api_version="v1beta1"))
model_id = "gemini-3.5-flash"

tools = []
tools.append(Tool(url_context=UrlContext))
tools.append(Tool(google_search=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)

API Interactions

from google import genai

client = genai.Client(
    enterprise=True,
    project="GOOGLE_CLOUD_PROJECT",
    location="global",
)

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Give me a three day event schedule based on YOUR_URL. Also let me know what needs to be taken care of considering weather and commute.",
    tools=[
        {"type": "url_context"},
        {"type": "google_search"},
    ],
)

print(interaction.output_text)

# Get URLs retrieved for context
for step in interaction.steps:
    if step.type == "url_context_result":
        for res in step.result:
            print(f"URL: {res.url} (Status: {res.status})")

JavaScript

API GenerateContent

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

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

const ai = new GoogleGenAI({
  vertexai: true,
  project: process.env.GOOGLE_CLOUD_PROJECT,
  location: process.env.GOOGLE_CLOUD_LOCATION,
  apiVersion: 'v1beta1',
});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-3.5-flash",
    contents: [
        "Give me a three day event 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();

API Interactions

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

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

const ai = new GoogleGenAI({
  enterprise: true,
  project: process.env.GOOGLE_CLOUD_PROJECT,
  location: process.env.GOOGLE_CLOUD_LOCATION,
});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Give me a three day event schedule based on YOUR_URL. Also let me know what needs to be taken care of considering weather and commute.",
    tools: [
      { type: "url_context" },
      { type: "google_search" },
    ],
  });

  console.log(interaction.output_text);

  for (const step of interaction.steps) {
    if (step.type === "url_context_result") {
      console.log(step.result);
    }
  }
}

await main();

REST

API GenerateContent

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

GOOGLE_CLOUD_PROJECT: il tuo ID progetto
YOUR_URL: l'URL da cui recuperare il contesto.

Metodo HTTP e URL:

POST https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/publishers/google/models/gemini-3.5-flash:generateContent

Corpo JSON della richiesta:

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Give me a three day event schedule based on YOUR_URL. Also let me know what needs to taken care of considering weather and commute."
        }
      ]
    }
  ],
  "tools": [
    {
      "url_context": {}
    },
    {
      "google_search": {}
    }
  ]
}

Per inviare la richiesta, scegli una di queste opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/publishers/google/models/gemini-3.5-flash:generateContent"

PowerShell

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/publishers/google/models/gemini-3.5-flash:generateContent" | Select-Object -Expand Content

API Interactions

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

GOOGLE_CLOUD_PROJECT: il tuo ID progetto
YOUR_URL: l'URL da cui recuperare il contesto.

Metodo HTTP e URL:

POST https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/interactions

Corpo JSON della richiesta:

{
  "model": "gemini-3.8-flash",
  "input": [
    {
      "type": "user_input",
      "content": [
        {
          "type": "text",
          "text": "Give me a three day event 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"
    }
  ]
}

Per inviare la richiesta, scegli una di queste opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/interactions"

PowerShell

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/interactions" | Select-Object -Expand Content

Per maggiori dettagli sul grounding con la Ricerca Google, consulta la pagina di panoramica.

Grounding web per aziende con contesto URL

Puoi attivare sia il contesto dell'URL sia Web Grounding for Enterprise se hai esigenze di conformità specifiche o se operi in un settore regolamentato come la sanità, la finanza o il settore pubblico. L'indice web utilizzato nel grounding web per Enterprise è più limitato rispetto all'indice di grounding con la Ricerca Google standard, in quanto utilizza un sottoinsieme di ciò che è disponibile nella Ricerca Google.

Per maggiori dettagli su Web Grounding per Enterprise, consulta la pagina Web Grounding per Enterprise.

Risposta contestuale

La risposta del modello si basa sui contenuti recuperati dagli URL. Se il modello ha recuperato contenuti dagli URL, la risposta includerà url_context_metadata. Una risposta di questo tipo potrebbe essere simile alla seguente (alcune parti della risposta sono state omesse per brevità):

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "... \n"
          }
        ],
        "role": "model"
      },
      ...
      "url_context_metadata":
      {
          "url_metadata":
          [
            {
              "retrieved_url": "https://cloud.google.com/gemini-enterprise-agent-platform/models/capabilities/code-execution",
              "url_retrieval_status": <UrlRetrievalStatus.URL_RETRIEVAL_STATUS_SUCCESS: "URL_RETRIEVAL_STATUS_SUCCESS">
            },
            {
              "retrieved_url": "https://cloud.google.com/gemini-enterprise-agent-platform/models/grounding/grounding-with-google-search",
              "url_retrieval_status": <UrlRetrievalStatus.URL_RETRIEVAL_STATUS_SUCCESS: "URL_RETRIEVAL_STATUS_SUCCESS">
            },
          ]
        }
    }
  ]
}

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

Recupero in tempo reale

Lo strumento di contesto degli URL recupera le versioni pubblicate delle pagine web per mantenere aggiornate le informazioni.

Per recuperare in modo efficiente i contenuti delle pagine web, lo strumento Contesto URL utilizza un processo in due fasi progettato per bilanciare velocità, costi e accesso alle informazioni più aggiornate:

Recupero dei contenuti indicizzati: questa è la prima fase. Quando fornisci un URL, lo strumento tenta innanzitutto di recuperare i contenuti dall'indice web completo e altamente ottimizzato di Google. Questo metodo fornisce un accesso rapido a una vasta raccolta di pagine web sottoposte a scansione.
Fallback di recupero in tempo reale: questa è la seconda fase. Se i contenuti di un determinato URL non sono disponibili nell'indice (ad esempio, se la pagina è molto recente e non è ancora stata indicizzata), lo strumento esegue automaticamente un recupero in tempo reale. Questo meccanismo di riserva può accedere direttamente all'URL e recuperare l'ultima versione dei contenuti in tempo reale.

Controlli di sicurezza

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

Conteggio dei token

Il conteggio dei token di input include i contenuti recuperati dagli URL specificati nel prompt. Dall'output del modello, puoi vedere il conteggio dei token per l'utilizzo del prompt e degli strumenti nell'oggetto usage_metadata. Di seguito è riportato un output di esempio:

'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 saperne di più, consulta Costo della creazione e del deployment di modelli di AI in Gemini Enterprise Agent Platform.

Tipi di contenuti supportati e non supportati

Lo strumento di contesto degli URL può estrarre contenuti da URL con i seguenti tipi di contenuti:

Contenuti	Tipo
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`

Lo strumento per il contesto URL non supporta i seguenti tipi di contenuti:

Contenuti protetti da paywall
Video di YouTube (per saperne di più, consulta Comprensione dei video)
File di Google Workspace come Documenti Google o Fogli Google
File video e audio

Limitazioni

Lo strumento URL Context consuma fino a 20 URL per richiesta di analisi.
Per risultati ottimali durante la fase sperimentale, utilizza lo strumento su pagine web standard anziché su contenuti multimediali come i video di YouTube.

Contesto URL Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Modelli supportati

Fai clic per espandere i modelli supportati

Usa il contesto URL

Solo contesto URL

Python

API GenerateContent

API Interactions

JavaScript

API GenerateContent

API Interactions

REST

API GenerateContent

curl

PowerShell

API Interactions

curl

PowerShell

Grounding con la Ricerca Google con contesto dell'URL

Python

API GenerateContent

API Interactions

JavaScript

API GenerateContent

API Interactions

REST

API GenerateContent

curl

PowerShell

API Interactions

curl

PowerShell

Grounding web per aziende con contesto URL

Risposta contestuale

Recupero in tempo reale

Controlli di sicurezza

Conteggio dei token

Tipi di contenuti supportati e non supportati

Limitazioni

Contesto URL