Browser API: headless-браузер для скриншотов, контента и данных

Browser API даёт доступ к headless Chromium и лёгкому HTTP-парсеру: скриншоты, полностью отрендеренный HTML, извлечение элементов по CSS-селекторам, PDF, Lighthouse-аудит и типизированное извлечение документов. Запросы выполняются с российских серверов, поэтому сайты отдают локализованный контент, цены в рублях и российскую выдачу.

Формат запросов совместим с Browserless: существующую интеграцию достаточно перенаправить на https://proxy.seyka.ru и сменить ключ. Все эндпоинты вызываются с заголовком Authorization: Bearer <ключ> — см. Аутентификация. Интерактивный справочник со всеми полями — proxy.seyka.ru/api-docs.

Эндпоинты

Smart ScrapePOST /v1/browser/smart-scrape — документ любым самым дешёвым путём: кэш, HTTP, браузер. Плюс пакетный Tavily Extract.

СкриншотыGET и POST /v1/browser/screenshot — PNG, JPEG или WebP страницы или HTML.

HTML-контентPOST /v1/browser/content — HTML страницы после выполнения JavaScript.

ScrapePOST /v1/browser/scrape — элементы по CSS-селекторам из отрендеренной страницы.

PDFPOST /v1/browser/pdf — PDF из страницы: формат, поля, колонтитулы.

PerformancePOST /v1/browser/performance — Lighthouse: производительность, доступность, SEO.

CheerioPOST /v1/browser/cheerio — элементы по CSS-селекторам без браузера, для серверных страниц.

Операция	Что возвращает
`POST /v1/browser/smart-scrape`	JSON: документ, его вид (`contentKind`), Markdown, ссылки, SEO-данные
`POST /v1/tavily/extract`	JSON в формате Tavily Extract, до 20 URL за запрос
`GET /v1/browser/screenshot`, `POST /v1/browser/screenshot`	изображение (`image/jpeg`, `image/png`, `image/webp`)
`POST /v1/browser/content`	`text/html`
`POST /v1/browser/scrape`	JSON с элементами по селекторам
`POST /v1/browser/pdf`	`application/pdf`
`POST /v1/browser/performance`	JSON с оценками и аудитами Lighthouse
`POST /v1/browser/cheerio`	JSON с элементами по селекторам

Какой эндпоинт выбрать

Нужен текст или Markdown страницы — Smart Scrape. Он сам решает, нужен ли браузер, и стоит дешевле, когда страницу можно получить без него.
Нужны конкретные элементы статической или серверной страницы — Cheerio: без запуска браузера, быстрее и дешевле.
Те же элементы, но страница строится JavaScript — Scrape.
Нужен итоговый DOM целиком — HTML-контент.
Нужна картинка или документ — скриншот или PDF.
Нужны Core Web Vitals и оценки Lighthouse — Performance.

Общие параметры страницы

Скриншот, HTML-контент, Scrape и PDF принимают один и тот же набор параметров страницы (Browserless PageOptions):

Параметр	Описание
`url`	адрес страницы (HTTP или HTTPS)
`html`	HTML для рендеринга вместо `url`; передаётся ровно одно из двух
`viewport`	`width`, `height` (1–4096, по умолчанию 1280×800)
`gotoOptions`	`waitUntil`: `load` (по умолчанию), `domcontentloaded`, `networkidle`; `networkidle0` и `networkidle2` трактуются как `networkidle`. `timeout` — таймаут навигации в мс, по умолчанию 10 000
`waitForSelector`	ждать селектор: `selector`, `timeout`, `visible`, `hidden`
`waitForFunction`	ждать, пока JavaScript-функция `fn` вернёт истину
`waitForEvent`	ждать событие страницы `event`
`waitForTimeout`	дополнительная пауза в мс
`bestAttempt`	продолжить, даже если условие ожидания не выполнилось
`userAgent`, `setExtraHTTPHeaders`, `cookies`, `authenticate`	идентичность запроса: User-Agent, заголовки, куки, HTTP Basic
`addScriptTag`, `addStyleTag`	внедрить скрипты и стили (`url` или `content`)
`rejectResourceTypes`, `rejectRequestPattern`	не загружать ресурсы по типу или шаблону URL
`emulateMediaType`	`screen` или `print`
`setJavaScriptEnabled`	`false` отключает JavaScript
`allowInsecureTLS`	открыть сайт с недействительным сертификатом (просрочен, самоподписан, чужое имя); по умолчанию выключено

Таймауты навигации и ожиданий не ограничены сверху, но весь запрос к screenshot, content, scrape и pdf — включая ожидание свободного браузера, загрузку и все ожидания — должен уложиться в 35 секунд: дольше шлюз не ждёт и отвечает 502. Для долгих страниц используйте Smart Scrape.

Заголовки ответа

Браузерные эндпоинты сообщают, что ответил сам сайт (набор зависит от эндпоинта: Smart Scrape передаёт только X-Response-URL, Cheerio — без X-Response-Status, Performance — ни одного):

X-Response-Code — HTTP-код целевой страницы;
X-Response-Status — его текстовый статус;
X-Response-URL — конечный URL после редиректов (для запроса с html не передаётся).

Кэш ответов включён у Smart Scrape и Performance; окно кэша и цена повтора — в таблице цен. Остальные браузерные эндпоинты всегда отвечают X-Cache: DISABLED. Значения заголовка X-Cache — в разделе Кэш ответов.

Ошибки

Если страница не открылась, ответ — JSON с полем error и, где возможно, типом сбоя errorKind и исходным кодом code:

{
  "error": "net::ERR_NAME_NOT_RESOLVED at https://no-such-host.example/",
  "errorKind": "dns",
  "code": "net::ERR_NAME_NOT_RESOLVED"
}

Код	Когда
`400`	запрос не прошёл проверку: нет `url` и `html` или переданы оба, неверный URL, адрес во внутренней сети
`502`	сайт не ответил: `errorKind` — `dns`, `tcp`, `tls`, `http` или `redirect_loop`
`503`	все браузеры заняты (`saturated`) или сервис перезапускается (`shutdown`); повторите после `Retry-After`
`504`	страница не загрузилась за отведённое время

Общие коды — 401, 402 и другие — описаны в разделе Ошибки.

Цена

Каждый эндпоинт оплачивается за вызов; Smart Scrape — по ступени, на которой получен документ. Цены — в таблице цен.

Миграция с Browserless

https://chrome.browserless.io/screenshot
https://proxy.seyka.ru/v1/browser/screenshot
https://chrome.browserless.io/content
https://proxy.seyka.ru/v1/browser/content
https://chrome.browserless.io/scrape
https://proxy.seyka.ru/v1/browser/scrape
https://chrome.browserless.io/pdf
https://proxy.seyka.ru/v1/browser/pdf
https://chrome.browserless.io/performance
https://proxy.seyka.ru/v1/browser/performance
https://production-sfo.browserless.io/smart-scrape
https://proxy.seyka.ru/v1/browser/smart-scrape

Ключ передаётся заголовком Authorization: Bearer, а не параметром token. Ответ Smart Scrape — надмножество Browserless: в нём есть обязательное поле contentKind, а content для HTML приходит очищенным; подробнее — на странице Smart Scrape.