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

Инструмент веб-загрузки в настоящее время находится в бета-версии. Чтобы включить его, используйте бета-заголовок web-fetch-2025-09-10 в ваших API-запросах.

Пожалуйста, используйте эту форму для предоставления отзывов о качестве ответов модели, самом API или качестве документации.

Включение инструмента веб-загрузки в средах, где Claude обрабатывает недоверенный ввод наряду с конфиденциальными данными, создает риски утечки данных. Мы рекомендуем использовать этот инструмент только в доверенных средах или при работе с неконфиденциальными данными.

Чтобы минимизировать риски утечки, Claude не разрешается динамически создавать URL. Claude может загружать только URL, которые были явно предоставлены пользователем или которые поступили из предыдущих результатов веб-поиска или веб-загрузки. Однако остается остаточный риск, который следует тщательно учитывать при использовании этого инструмента.

Если утечка данных вызывает беспокойство, рассмотрите:

  • Полное отключение инструмента веб-загрузки
  • Использование параметра max_uses для ограничения количества запросов
  • Использование параметра allowed_domains для ограничения известными безопасными доменами

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

Веб-загрузка доступна на:

  • Claude Opus 4.1 (claude-opus-4-1-20250805)
  • Claude Opus 4 (claude-opus-4-20250514)
  • Claude Sonnet 4 (claude-sonnet-4-20250514)
  • Claude Sonnet 3.7 (claude-3-7-sonnet-20250219)
  • Claude Sonnet 3.5 v2 (устарела) (claude-3-5-sonnet-latest)
  • Claude Haiku 3.5 (claude-3-5-haiku-latest)

​
Как работает веб-загрузка

Когда вы добавляете инструмент веб-загрузки в ваш API-запрос:

  1. Claude решает, когда загружать содержимое, основываясь на промпте и доступных URL.
  2. API получает полное текстовое содержимое с указанного URL.
  3. Для PDF выполняется автоматическое извлечение текста.
  4. Claude анализирует загруженное содержимое и предоставляет ответ с необязательными цитатами.

​
Как использовать веб-загрузку

Предоставьте инструмент веб-загрузки в вашем API-запросе:

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: web-fetch-2025-09-10" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-1-20250805",
        "max_tokens": 1024,
        "messages": [
            {
                "role": "user",
                "content": "Пожалуйста, проанализируйте содержимое по адресу https://example.com/article"
            }
        ],
        "tools": [{
            "type": "web_fetch_20250910",
            "name": "web_fetch",
            "max_uses": 5
        }]
    }'

​
Определение инструмента

Инструмент веб-загрузки поддерживает следующие параметры:

JSON
{
  "type": "web_fetch_20250910",
  "name": "web_fetch",

  // Необязательно: Ограничить количество загрузок на запрос
  "max_uses": 10,

  // Необязательно: Загружать только с этих доменов
  "allowed_domains": ["example.com", "docs.example.com"],

  // Необязательно: Никогда не загружать с этих доменов
  "blocked_domains": ["private.example.com"],

  // Необязательно: Включить цитаты для загруженного содержимого
  "citations": {
    "enabled": true
  },

  // Необязательно: Максимальная длина содержимого в токенах
  "max_content_tokens": 100000
}

​
Максимальное использование

Параметр max_uses ограничивает количество выполняемых веб-загрузок. Если Claude попытается выполнить больше загрузок, чем разрешено, web_fetch_tool_result будет ошибкой с кодом ошибки max_uses_exceeded. В настоящее время нет ограничения по умолчанию.

​
Фильтрация доменов

При использовании фильтров доменов:

  • Домены не должны включать схему HTTP/HTTPS (используйте example.com вместо https://example.com)
  • Поддомены автоматически включаются (example.com покрывает docs.example.com)
  • Поддерживаются подпути (example.com/blog)
  • Вы можете использовать либо allowed_domains, либо blocked_domains, но не оба в одном запросе.

Имейте в виду, что символы Unicode в доменных именах могут создавать уязвимости безопасности через атаки гомографов, где визуально похожие символы из разных скриптов могут обойти фильтры доменов. Например, аmazon.com (используя кириллическую ‘а’) может выглядеть идентично amazon.com, но представляет другой домен.

При настройке списков разрешенных/заблокированных доменов:

  • Используйте доменные имена только в ASCII, когда это возможно
  • Учитывайте, что парсеры URL могут по-разному обрабатывать нормализацию Unicode
  • Тестируйте ваши фильтры доменов с потенциальными вариациями гомографов
  • Регулярно проверяйте ваши конфигурации доменов на подозрительные символы Unicode

​
Ограничения содержимого

Параметр max_content_tokens ограничивает количество содержимого, которое будет включено в контекст. Если загруженное содержимое превышает этот лимит, оно будет обрезано. Это помогает контролировать использование токенов при загрузке больших документов.

Лимит параметра max_content_tokens является приблизительным. Фактическое количество используемых входных токенов может незначительно варьироваться.

​
Цитаты

В отличие от веб-поиска, где цитаты всегда включены, цитаты для веб-загрузки необязательны. Установите "citations": {"enabled": true}, чтобы позволить Claude цитировать конкретные отрывки из загруженных документов.

При отображении веб-результатов или информации, содержащейся в веб-результатах, конечным пользователям, встроенные цитаты должны быть четко видимыми и кликабельными в вашем пользовательском интерфейсе.

​
Ответ

Вот пример структуры ответа:

{
  "role": "assistant",
  "content": [
    // 1. Решение Claude о загрузке
    {
      "type": "text",
      "text": "Я загружу содержимое из статьи для анализа."
    },
    // 2. Запрос на загрузку
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01234567890abcdef",
      "name": "web_fetch",
      "input": {
        "url": "https://example.com/article"
      }
    },
    // 3. Результаты загрузки
    {
      "type": "web_fetch_tool_result",
      "tool_use_id": "srvtoolu_01234567890abcdef",
      "content": {
        "type": "web_fetch_result",
        "url": "https://example.com/article",
        "content": {
          "type": "document",
          "source": {
            "type": "text",
            "media_type": "text/plain",
            "data": "Полное текстовое содержимое статьи..."
          },
          "title": "Заголовок статьи",
          "citations": {"enabled": true}
        },
        "retrieved_at": "2025-08-25T10:30:00Z"
      }
    },
    // 4. Анализ Claude с цитатами (если включены)
    {
      "text": "На основе статьи, ",
      "type": "text"
    },
    {
      "text": "основной представленный аргумент заключается в том, что искусственный интеллект преобразует здравоохранение",
      "type": "text",
      "citations": [
        {
          "type": "char_location",
          "document_index": 0,
          "document_title": "Заголовок статьи",
          "start_char_index": 1234,
          "end_char_index": 1456,
          "cited_text": "Искусственный интеллект готов революционизировать предоставление медицинских услуг..."
        }
      ]
    }
  ],
  "id": "msg_a930390d3a",
  "usage": {
    "input_tokens": 25039,
    "output_tokens": 931,
    "server_tool_use": {
      "web_fetch_requests": 1
    }
  },
  "stop_reason": "end_turn"
}

​
Результаты загрузки

Результаты загрузки включают:

  • url: URL, который был загружен
  • content: Блок документа, содержащий загруженное содержимое
  • retrieved_at: Временная метка, когда содержимое было получено

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

Для PDF-документов содержимое будет возвращено как данные в кодировке base64:

{
  "type": "web_fetch_tool_result",
  "tool_use_id": "srvtoolu_02",
  "content": {
    "type": "web_fetch_result",
    "url": "https://example.com/paper.pdf",
    "content": {
      "type": "document",
      "source": {
        "type": "base64",
        "media_type": "application/pdf",
        "data": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmo..."
      },
      "citations": {"enabled": true}
    },
    "retrieved_at": "2025-08-25T10:30:02Z"
  }
}

​
Ошибки

Когда инструмент веб-загрузки сталкивается с ошибкой, Anthropic API возвращает ответ 200 (успех) с ошибкой, представленной в теле ответа:

{
  "type": "web_fetch_tool_result",
  "tool_use_id": "srvtoolu_a93jad",
  "content": {
    "type": "web_fetch_tool_error",
    "error_code": "url_not_accessible"
  }
}

Это возможные коды ошибок:

  • invalid_input: Неверный формат URL
  • url_too_long: URL превышает максимальную длину (250 символов)
  • url_not_allowed: URL заблокирован правилами фильтрации доменов и ограничениями модели
  • url_not_accessible: Не удалось загрузить содержимое (ошибка HTTP)
  • too_many_requests: Превышен лимит скорости
  • unsupported_content_type: Тип содержимого не поддерживается (только текст и PDF)
  • max_uses_exceeded: Превышено максимальное использование инструмента веб-загрузки
  • unavailable: Произошла внутренняя ошибка

​
Валидация URL

По соображениям безопасности инструмент веб-загрузки может загружать только URL, которые ранее появлялись в контексте разговора. Это включает:

  • URL в сообщениях пользователя
  • URL в результатах клиентских инструментов
  • URL из предыдущих результатов веб-поиска или веб-загрузки

Инструмент не может загружать произвольные URL, которые генерирует Claude, или URL из серверных инструментов на основе контейнеров (выполнение кода, Bash и т.д.).

​
Комбинированный поиск и загрузка

Веб-загрузка работает бесшовно с веб-поиском для комплексного сбора информации:

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-1-20250805",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Найдите недавние статьи о квантовых вычислениях и подробно проанализируйте наиболее релевантную"
        }
    ],
    tools=[
        {
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 3
        },
        {
            "type": "web_fetch_20250910",
            "name": "web_fetch",
            "max_uses": 5,
            "citations": {"enabled": True}
        }
    ],
    extra_headers={
        "anthropic-beta": "web-fetch-2025-09-10"
    }
)

В этом рабочем процессе Claude будет:

  1. Использовать веб-поиск для поиска релевантных статей
  2. Выбирать наиболее перспективные результаты
  3. Использовать веб-загрузку для получения полного содержимого
  4. Предоставлять подробный анализ с цитатами

​
Кэширование промптов

Веб-загрузка работает с кэшированием промптов. Чтобы включить кэширование промптов, добавьте точки останова cache_control в ваш запрос. Кэшированные результаты загрузки могут быть повторно использованы в разных поворотах разговора.

import anthropic

client = anthropic.Anthropic()

# Первый запрос с веб-загрузкой
messages = [
    {
        "role": "user",
        "content": "Проанализируйте эту исследовательскую работу: https://arxiv.org/abs/2024.12345"
    }
]

response1 = client.messages.create(
    model="claude-opus-4-1-20250805",
    max_tokens=1024,
    messages=messages,
    tools=[{
        "type": "web_fetch_20250910",
        "name": "web_fetch"
    }],
    extra_headers={
        "anthropic-beta": "web-fetch-2025-09-10"
    }
)

# Добавить ответ Claude в разговор
messages.append({
    "role": "assistant",
    "content": response1.content
})

# Второй запрос с точкой останова кэша
messages.append({
    "role": "user",
    "content": "Какую методологию использует работа?",
    "cache_control": {"type": "ephemeral"}
})

response2 = client.messages.create(
    model="claude-opus-4-1-20250805",
    max_tokens=1024,
    messages=messages,
    tools=[{
        "type": "web_fetch_20250910",
        "name": "web_fetch"
    }],
    extra_headers={
        "anthropic-beta": "web-fetch-2025-09-10"
    }
)

# Второй ответ использует кэшированные результаты загрузки
print(f"Токены чтения кэша: {response2.usage.get('cache_read_input_tokens', 0)}")

​
Потоковая передача

При включенной потоковой передаче события загрузки являются частью потока с паузой во время получения содержимого:

event: message_start
data: {"type": "message_start", "message": {"id": "msg_abc123", "type": "message"}}

event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}}

// Решение Claude о загрузке

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "web_fetch"}}

// URL загрузки передается потоком
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"url\":\"https://example.com/article\"}"}}

// Пауза во время выполнения загрузки

// Результаты загрузки передаются потоком
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "web_fetch_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": {"type": "web_fetch_result", "url": "https://example.com/article", "content": {"type": "document", "source": {"type": "text", "media_type": "text/plain", "data": "Содержимое статьи..."}}}}}

// Ответ Claude продолжается...

​
Пакетные запросы

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

​
Использование и ценообразование

Web fetch usage has no additional charges beyond standard token costs:

"usage": {
  "input_tokens": 25039,
  "output_tokens": 931,
  "cache_read_input_tokens": 0,
  "cache_creation_input_tokens": 0,
  "server_tool_use": {
    "web_fetch_requests": 1
  }
}

The web fetch tool is available on the Anthropic API at no additional cost. You only pay standard token costs for the fetched content that becomes part of your conversation context.

To protect against inadvertently fetching large content that would consume excessive tokens, use the max_content_tokens parameter to set appropriate limits based on your use case and budget considerations.

Example token usage for typical content:

  • Average web page (10KB): ~2,500 tokens
  • Large documentation page (100KB): ~25,000 tokens
  • Research paper PDF (500KB): ~125,000 tokens