Извлечение данных из нескольких URL через API удобно делать одним пакетным запросом к Contents: сервис принимает список страниц и возвращает отдельный результат для каждого адреса. Такой подход упрощает загрузку контента для AI-агента, сравнение документов и подготовку данных для RAG, не смешивая успешные страницы с ошибками.
Когда нужен Contents API
Contents API полезен, когда адреса уже известны. Например, поисковый шаг нашёл десять страниц, пользователь передал список документов или автоматизация должна регулярно читать одинаковый набор источников. В этой ситуации повторный веб-поиск не нужен: приложению требуется получить чистый текст, метаданные и ссылки по конкретным URL.
Это отличается от обычного scraping-конвейера. scrape решает задачу одной страницы, map находит адреса внутри сайта, а crawl обходит связанный раздел. POST /v1/contents работает с готовым списком от одного до ста URL и возвращает результат по каждому элементу. Общую схему выбора операций можно посмотреть в руководстве про web scraping для AI.
Сформируйте минимальный запрос
Для чтения текста достаточно передать URL и включить поле text. Ключ храните только на сервере или в защищённом хранилище автоматизации.
curl https://api.llmtokenapi.ru/v1/contents \
-H "Authorization: Bearer $LLMTOKENAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"urls": [
"https://example.com/docs/start",
"https://example.com/docs/auth"
],
"text": { "maxCharacters": 20000 },
"extras": { "links": 10 },
"maxAgeHours": 24
}'
Поле text.maxCharacters ограничивает объём текста на страницу. Это помогает заранее контролировать контекст следующего шага и не отправлять модели длинную навигацию или повторяющиеся блоки. extras.links добавляет ограниченное число ссылок, если приложению нужно продолжить обход самостоятельно.
Обрабатывайте результат по каждому URL
Не считайте пакет атомарным. Один адрес может загрузиться успешно, другой — вернуть запрет, тайм-аут или ошибку извлечения. Поэтому приложение должно проходить по массиву результатов и принимать решение отдельно для каждой страницы: сохранить успешный текст, поставить временную ошибку на повтор, а постоянную — отправить в журнал.
Так частичный сбой не уничтожит полезную работу всего пакета. Для наблюдаемости сохраняйте исходный URL, итоговый URL после перенаправлений, статус, время выполнения и причину ошибки. Сам текст храните только там, где это действительно нужно продукту и разрешено вашей политикой данных.
Используйте кэш осознанно
maxAgeHours задаёт допустимый возраст сохранённого результата. Для стабильной документации можно разрешить кэш на сутки или дольше, а для страницы со свежими изменениями — сократить окно. Значение зависит не от типа сайта, а от того, насколько устаревшая информация допустима в конкретном ответе.
HTTP-кэширование в целом отделяет свежий ответ от устаревшего и позволяет повторно использовать представление по заданным правилам; базовая модель описана в RFC 9111. Параметр Contents API не заменяет заголовки сайта, но даёт клиенту явный контроль над допустимой давностью результата.
Добавляйте highlights вместо полного текста
Если следующему шагу нужны только фрагменты по вопросу, включите highlights и передайте запрос. Например, для сравнения условий возврата можно искать фрагменты про срок, исключения и способ обращения. Это уменьшает объём данных, который попадёт в промпт, и делает происхождение ответа понятнее.
Не подменяйте highlights готовым фактом. Фрагмент остаётся частью исходной страницы: модель должна учитывать контекст, дату и качество источника. Для решений с высокой ценой ошибки сохраняйте ссылку и показывайте пользователю, на какой странице найдено подтверждение.
Когда включать summary и схему
Сводка полезна, если каждой странице нужно одинаковое краткое описание. Для машинной обработки можно задать локальную JSON Schema и получить предсказуемую структуру, например объект с названием продукта, ограничениями и датой обновления. Схема должна быть небольшой и описывать только реально нужные поля.
Сначала проверьте качество чистого текста на нескольких страницах, затем добавляйте сводку. Иначе трудно понять, возникла ошибка при загрузке, извлечении или интерпретации. Полные параметры запроса и актуальные ограничения всегда сверяйте в документации LLMTOKENAPI.
Соберите надёжный конвейер
Практический конвейер состоит из пяти шагов: получить URL, удалить дубли, отправить пакет в Contents API, разобрать статусы отдельных страниц и передать только подходящий контент следующему инструменту. Ограничивайте параллелизм и размер пакета на своей стороне, даже если контракт допускает до ста адресов.
Для RAG дополнительно сохраняйте канонический URL и время получения рядом с фрагментом. Для AI-агента передавайте только релевантный текст и ссылки на источники. Для мониторинга сравнивайте нормализованные поля, а не весь HTML: так изменения меню и счётчиков не будут выглядеть как содержательное обновление.
Contents API особенно полезен как граница между получением веб-страниц и логикой продукта. Приложение знает, какие адреса ему нужны, API возвращает нормализованные результаты, а модель получает ограниченный и проверяемый контекст вместо произвольной выдачи из интернета.
