контекст URL

Инструмент контекста URL позволяет предоставлять моделям дополнительный контекст в виде URL-адресов. Включив URL-адреса в запрос, модель получит доступ к содержимому этих страниц (при условии, что это не тип URL, указанный в разделе ограничений ), чтобы улучшить и оптимизировать свой ответ.

Инструмент «Контекст URL» полезен для решения следующих задач:

• Извлечение данных : Получение конкретной информации, такой как цены, имена или ключевые результаты, из нескольких URL-адресов.
• Сравнение документов : анализируйте несколько отчетов, статей или PDF-файлов, чтобы выявить различия и отследить тенденции.
• Синтез и создание контента : Объединяйте информацию из нескольких источников по URL-адресам для создания точных сводок, сообщений в блоге или отчетов.
• Анализ кода и документации : Указывайте на репозиторий GitHub или техническую документацию, чтобы объяснить код, сгенерировать инструкции по настройке или ответить на вопросы.

В следующем примере показано, как сравнить два рецепта с разных веб-сайтов.

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

Как это работает

Инструмент «Контекст URL» использует двухэтапный процесс получения данных для достижения баланса между скоростью, стоимостью и доступом к актуальным данным. При указании URL-адреса инструмент сначала пытается получить контент из внутреннего индексного кэша. Этот кэш является высокооптимизированным. Если URL-адрес отсутствует в индексе (например, если это совершенно новая страница), инструмент автоматически переключается на получение данных в реальном времени. Это позволяет напрямую получить доступ к URL-адресу и получить его контент в режиме реального времени.

В сочетании с другими инструментами

Инструмент анализа контекста URL-адреса можно комбинировать с другими инструментами для создания более эффективных рабочих процессов.

Модели Gemini 3 поддерживают сочетание встроенных инструментов (например, контекста URL) с пользовательскими инструментами (вызовом функций). Подробнее см. на странице, посвященной сочетаниям инструментов .

Обоснование с помощью поиска

Когда включены и контекст URL, и привязка к поиску Google , модель может использовать свои поисковые возможности для поиска релевантной информации в интернете, а затем использовать инструмент контекста URL для более глубокого понимания найденных страниц. Этот подход эффективен для запросов, требующих как широкого поиска, так и глубокого анализа конкретных страниц.

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

Понимание ответа

Когда модель использует инструмент контекста URL, её текстовый ответ включает встроенные аннотации url_citation в блоке текстового содержимого. Каждая аннотация связывает сегмент текста ответа (через start_index и end_index ) с исходным URL-адресом, из которого он был получен. Это основной способ отображения цитат в вашем приложении — см. основной пример выше, чтобы узнать, как их извлечь.

В ответ также входит шаг url_context_result с метаданными о каждой попытке получения URL-адреса (статус, полученный URL). Это в основном полезно для отладки.

проверки безопасности

Система выполняет проверку контента URL-адресов на соответствие стандартам безопасности. Если URL-адрес не проходит эту проверку, на соответствующем этапе url_context_result будет отображаться status "unsafe" .

Количество токенов

Содержимое, полученное с URL-адресов, указанных в вашем запросе, учитывается как часть входных токенов. Количество токенов можно увидеть в объекте usage взаимодействия. Ниже приведен пример:

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

Цена за токен зависит от используемой модели, подробности смотрите на странице с ценами .

Поддерживаемые модели

Передовые методы

• Укажите конкретные URL-адреса : Для достижения наилучших результатов укажите прямые URL-адреса контента, который вы хотите, чтобы модель анализировала. Модель будет извлекать контент только по указанным вами URL-адресам, а не контент из вложенных ссылок.
• Проверьте доступность : убедитесь, что предоставленные вами URL-адреса не ведут на страницы, требующие авторизации или находящиеся за платным доступом.
• Укажите полный URL-адрес : укажите полный URL-адрес, включая протокол (например, https://www.google.com вместо просто google.com).

Ограничения

• Вызов функций: Использование инструментов (контекст URL, привязка к поиску Google и т. д.) при вызове функций в настоящее время не поддерживается.
• Ограничение на количество запросов: инструмент может обрабатывать до 20 URL-адресов за один запрос.
• Размер содержимого URL-адреса: максимальный размер содержимого, загружаемого с одного URL-адреса, составляет 34 МБ.
• Доступность для всех: URL-адреса должны быть общедоступны в сети Интернет. Адреса локальных хостов (например, localhost, 127.0.0.1), частные сети и туннельные сервисы (например, ngrok, pinggy) не поддерживаются.
• Доступ к контексту URL-адреса возможен только через API Gemini: эта функция доступна только в API Gemini, а не через платформу Gemini Enterprise Agent.

Поддерживаемые и неподдерживаемые типы контента

Инструмент может извлекать контент из URL-адресов, содержащих следующие типы данных:

• Текст (text/html, application/json, text/plain, text/xml, text/css, text/javascript, text/csv, text/rtf)
• Изображение (image/png, image/jpeg, image/bmp, image/webp)
• PDF (application/pdf)

Следующие типы контента не поддерживаются:

• Контент, доступ к которому платный.
• Видео на YouTube (см. раздел «Понимание видео» , чтобы узнать, как обрабатывать URL-адреса YouTube).
• Файлы рабочих пространств Google, такие как документы Google или электронные таблицы Google.
• Видео- и аудиофайлы