Contexto de URL

La herramienta de contexto de URL te permite proporcionar contexto adicional a los modelos en forma de URLs. Si incluyes URLs en tu solicitud, el modelo accederá al contenido de esas páginas (siempre y cuando no se trate de un tipo de URL que se indique en la sección de limitaciones) para fundamentar y mejorar su respuesta.

La herramienta de contexto de URL es útil para tareas como las siguientes:

• Extraer datos: Extrae información específica, como precios, nombres o hallazgos clave, de varias URLs.
• Compare Documents: Analiza varios informes, artículos o PDFs para identificar diferencias y hacer un seguimiento de las tendencias.
• Sintetizar y crear contenido: Combina información de varias URLs de origen para generar resúmenes, informes o publicaciones de blog precisos.
• Analizar código y documentos: Indica un repositorio de GitHub o documentación técnica para explicar el código, generar instrucciones de configuración o responder preguntas.

En el siguiente ejemplo, se muestra cómo comparar dos recetas de diferentes sitios web.

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-flash-preview",
    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}")

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

const client = new GoogleGenAI({});

async function main() {
  const interaction = await client.interactions.create({
    model: "gemini-3-flash-preview",
    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();

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "model": "gemini-3-flash-preview",
      "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"}]
  }'

Cómo funciona

La herramienta Contexto de URL utiliza un proceso de recuperación de dos pasos para equilibrar la velocidad, el costo y el acceso a datos recientes. Cuando proporcionas una URL, la herramienta primero intenta recuperar el contenido de una caché de índice interna. Esto actúa como una caché altamente optimizada. Si una URL no está disponible en el índice (por ejemplo, si es una página muy nueva), la herramienta recurre automáticamente a realizar una recuperación en vivo. Esto accede directamente a la URL para recuperar su contenido en tiempo real.

Combinación con otras herramientas

Puedes combinar la herramienta de contexto de URL con otras herramientas para crear flujos de trabajo más potentes.

Los modelos de Gemini 3 admiten la combinación de herramientas integradas (como Contexto de URL) con herramientas personalizadas (llamadas a funciones). Obtén más información en la página de combinaciones de herramientas.

Fundamentación con la búsqueda

Cuando se habilitan el contexto de URL y la Fundamentación con la Búsqueda de Google, el modelo puede usar sus capacidades de búsqueda para encontrar información relevante en línea y, luego, usar la herramienta de contexto de URL para comprender mejor las páginas que encuentra. Este enfoque es eficaz para las instrucciones que requieren una búsqueda amplia y un análisis profundo de páginas específicas.

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    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)

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

const client = new GoogleGenAI({});

async function main() {
  const interaction = await client.interactions.create({
    model: "gemini-3-flash-preview",
    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();

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "model": "gemini-3-flash-preview",
      "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"}
      ]
  }'

Cómo comprender la respuesta

Cuando el modelo usa la herramienta de contexto de URL, su respuesta de texto incluye anotaciones url_citation intercaladas en el bloque de contenido de texto. Cada anotación vincula un segmento del texto de respuesta (a través de start_index y end_index) a la URL de origen de la que se derivó. Esta es la forma principal de mostrar citas en tu aplicación. Consulta el ejemplo principal anterior para saber cómo extraerlas.

La respuesta también incluye un paso url_context_result con metadatos sobre cada intento de recuperación de URL (estado, URL recuperada). Esto es útil principalmente para la depuración.

Verificaciones de seguridad

El sistema realiza una verificación de moderación de contenido en las URLs para confirmar que cumplen con los estándares de seguridad. Si una URL no supera esta verificación, el paso url_context_result correspondiente mostrará un status de "unsafe".

Recuento de tokens

El contenido recuperado de las URLs que especificas en tu instrucción se cuenta como parte de los tokens de entrada. Puedes ver el recuento de tokens en el objeto usage de la interacción. A continuación, se muestra un ejemplo:

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

El precio por token depende del modelo que se use. Consulta la página de precios para obtener más detalles.

Modelos compatibles

Prácticas recomendadas

• Proporciona URLs específicas: Para obtener los mejores resultados, proporciona URLs directas al contenido que deseas que analice el modelo. El modelo solo recuperará contenido de las URLs que proporciones, no de los vínculos anidados.
• Verifica la accesibilidad: Comprueba que las URLs que proporciones no dirijan a páginas que requieran un acceso o estén detrás de un muro de pago.
• Usa la URL completa: Proporciona la URL completa, incluido el protocolo (p.ej., https://www.google.com en lugar de solo google.com).

Limitaciones

• Llamadas a funciones: Actualmente, no se admite el uso de herramientas (contexto de URL, fundamentación con la Búsqueda de Google, etc.) con llamadas a funciones.
• Límite de solicitudes: La herramienta puede procesar hasta 20 URLs por solicitud.
• Tamaño del contenido de la URL: El tamaño máximo del contenido recuperado de una sola URL es de 34 MB.
• Accesibilidad pública: Las URLs deben ser de acceso público en la Web. No se admiten las direcciones de localhost (p.ej., localhost, 127.0.0.1), las redes privadas ni los servicios de tunelización (p.ej., ngrok, pinggy).
• Solo en la API de Gemini: El contexto de URL solo está disponible en la API de Gemini, no a través de Agent Platform de Gemini Enterprise.

Tipos de contenido admitidos y no admitidos

La herramienta puede extraer contenido de URLs con los siguientes tipos de contenido:

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

No se admiten los siguientes tipos de contenido:

• Contenido pago
• Videos de YouTube (consulta la comprensión de videos para obtener información sobre cómo procesar URLs de YouTube)
• Archivos de Google Workspace, como documentos u hojas de cálculo de Google
• Archivos de audio y video