Скриншоты

Параметры скриншота и PDF

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

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

Проверка URL

Имя хоста должно разрешаться в публичный IP-адрес. Shotly отклоняет localhost, частные IP-адреса, а также адреса link-local, multicast и CGNAT и отдельные зарезервированные диапазоны.

Если URL содержит секретные параметры, передавайте его в JSON-теле POST, а не в строке запроса GET /take.

Нормализация значений

browser и format приводятся к нижнему регистру, а jpg — к jpeg. Для бинарного ответа Shotly возвращает image/png, image/jpeg, image/webp или application/pdf в зависимости от выбранного формата.

Сейчас публичный API принимает только chromium. Firefox и WebKit временно недоступны.

Как передавать параметры

Асинхронный POST /v1/screenshots и синхронный POST /take принимают эти поля в JSON. Для совместимости GET /take принимает те же параметры в строке запроса.

POST /take отклоняет неизвестные поля. API не поддерживает параметры width, height, delay, headers, cookies, quality и эмуляцию устройства. Используйте точные имена selector, hideSelectors, imageQuality, delayMs и waitForSelector.

Значения по умолчанию

Для запроса достаточно одного поля:

{
  "url": "https://example.com"
}

Остальные параметры получат значения:

browser = chromium
format = png
fullPage = true
selector = отсутствует
waitUntil = автоматически (поле отсутствует)
delayMs = 0
waitForSelector = отсутствует
hideSelectors = отсутствует
imageQuality = отсутствует

Что попадёт в снимок

По умолчанию fullPage=true, поэтому Shotly снимает всю страницу. Значение false ограничивает снимок текущей областью просмотра. Чтобы получить изображение одного блока без ручной обрезки, передайте selector:

{
  "url": "https://example.com",
  "selector": ".pricing-card"
}

Shotly выбирает первый видимый элемент, подходящий под CSS-селектор, прокручивает его в область просмотра и снимает его реальные границы. Пробелы по краям удаляются. Пустое значение, управляющие символы и селекторы длиннее 256 символов отклоняются до создания задачи. Синтаксис CSS проверяется в Chromium.

Поле selector нельзя сочетать с fullPage=true. Если fullPage отсутствует, Shotly автоматически использует режим элемента. Ширина и высота области просмотра задаются от 1 до 4096 CSS-пикселей. При масштабе 2× ширина и высота результата удваиваются. Границы элемента должны быть положительными и конечными, а физическая площадь результата не может превышать 16 777 216 пикселей.

Как скрыть элементы

Передайте hideSelectors, чтобы перед созданием результата скрыть ненужные блоки. Поддерживаются только обычные CSS-селекторы Chromium: Shotly скрывает все элементы, подходящие под каждый селектор. Если совпадений нет, задача продолжается без ошибки.

{
  "url": "https://example.com",
  "hideSelectors": [
    ".cookie-banner"
  ]
}

Селекторы обрабатываются в порядке массива. Можно передать не больше 10 селекторов, до 256 Unicode-символов каждый и до 1024 Unicode-символов суммарно. Пробелы по краям удаляются; пустые значения, NUL и запрещённые управляющие символы отклоняются до создания задачи.

{
  "url": "https://example.com",
  "hideSelectors": [
    "header",
    ".advertisement",
    "#chat-widget"
  ],
  "fullPage": true
}

selector выбирает область снимка, а hideSelectors убирает элементы внутри страницы. Сначала Shotly скрывает совпадения, затем ищет элемент для снимка. Если скрываемый селектор скрыл сам снимаемый элемент, применяется обычная ошибка снимка невидимого элемента.

{
  "url": "https://example.com",
  "selector": "main",
  "hideSelectors": [
    "main .advertisement"
  ]
}

Скрытие поддерживается и для PDF. Оно выполняется после готовности страницы, ожидания waitForSelector и delayMs, но до снимка или печати. Элементы получают display: none !important, поэтому компоновка страницы и высота полноэкранного результата могут измениться.

{
  "url": "https://example.com/report",
  "format": "pdf",
  "hideSelectors": [
    "nav",
    ".floating-controls"
  ]
}

Синтаксис селекторов проверяет Chromium. Некорректный CSS приводит к безопасной ошибке задачи INVALID_HIDE_SELECTOR; внутреннее сообщение браузера не возвращается. Автоматическое обнаружение баннеров cookie или рекламы не выполняется. Пользовательские JavaScript и CSS не поддерживаются. Функция доступна только в Chromium.

Формат и качество изображения

Shotly создаёт изображения PNG, JPEG и WebP. WebP подходит, когда важен меньший размер файла при сохранении хорошей детализации. Поле imageQuality управляет сжатием только JPEG и WebP:

{
  "url": "https://example.com",
  "format": "jpeg",
  "imageQuality": 85
}

{
  "url": "https://example.com",
  "format": "webp",
  "imageQuality": 70
}

{
  "url": "https://example.com",
  "format": "jpeg",
  "imageQuality": 75,
  "fullPage": true
}

{
  "url": "https://example.com",
  "format": "webp",
  "imageQuality": 90,
  "selector": ".product-card"
}

imageQuality принимает только целое число от 1 до 100. Большее значение обычно сохраняет больше деталей, но увеличивает файл. Результат зависит от содержимого страницы, поэтому одинаковое значение не гарантирует одинаковый размер разных изображений.

Если поле отсутствует, Shotly использует автоматическое качество Chromium без публично обещанного числового значения. Это сохраняет прежнее поведение запросов. Поле нельзя передавать для PNG или PDF: такой запрос отклоняется до создания задачи с кодом IMAGE_QUALITY_FORMAT_CONFLICT. Дробные числа, логические значения, строки и значения вне диапазона отклоняются как INVALID_IMAGE_QUALITY.

Качество не меняет размеры изображения или область снимка. Один принятый результат расходует одну обычную единицу квоты. PNG остаётся форматом без настройки качества, а PDF сохраняет отдельный фиксированный контракт. Пользовательские алгоритмы сжатия, изменение размера после снимка и дополнительные параметры кодировщика не поддерживаются. JPEG и WebP с настраиваемым качеством доступны только в Chromium; WebP с другим браузером отклоняется до создания задачи с кодом WEBP_BROWSER_UNSUPPORTED.

PDF-документ

PDF создаётся напрямую в Chromium: формат бумаги — A4, ориентация — книжная, медиатип — screen, фоновая графика включена, поля равны нулю, колонтитулы отключены, размер из CSS @page не применяется, в документ входят все страницы.

{
  "url": "https://example.com/report",
  "format": "pdf"
}

viewportWidth и viewportHeight выбирают мобильную или настольную адаптивную версию до печати, но не меняют физический A4. Для PDF доступны waitUntil, delayMs, waitForSelector и hideSelectors, включая совместимый автоматический режим.

{
  "url": "https://example.com/report",
  "format": "pdf",
  "viewportWidth": 1440,
  "viewportHeight": 900,
  "waitUntil": "networkidle"
}

PDF нельзя сочетать с selector, fullPage=true или deviceScaleFactor=2; такие запросы отклоняются до создания задачи с кодами PDF_SELECTOR_CONFLICT, PDF_FULL_PAGE_CONFLICT и PDF_DEVICE_SCALE_CONFLICT. Один принятый PDF расходует одну обычную единицу квоты. Результат имеет application/pdf и имя файла с расширением .pdf. PDF поддерживается только Chromium.

Воркер ограничивает высоту документа и размер PDF. Безопасные коды ошибок: PDF_DOCUMENT_TOO_LARGE, PDF_OUTPUT_TOO_LARGE и PDF_RENDER_FAILED; внутренние ошибки Chromium не раскрываются.

Готовность страницы

Если поле waitUntil отсутствует, Shotly использует автоматический совместимый режим: выполняет навигацию до domcontentloaded, затем до 5 секунд старается дождаться сетевого покоя. Если сетевой покой не наступил, создание снимка продолжается. Так работают прежние запросы и исторические задачи.

Чтобы привязать снимок к определённому событию, передайте явное значение. load ждёт полной загрузки, domcontentloaded — загрузки HTML, а networkidle — окончания сетевой активности. Для явного режима дополнительное автоматическое ожидание сетевого покоя не применяется. networkidle не подходит некоторым страницам с постоянными подключениями.

{
  "url": "https://example.com",
  "waitUntil": "networkidle"
}

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

{
  "url": "https://example.com",
  "delayMs": 2000
}

waitForSelector ждёт, пока к DOM будет присоединён хотя бы один подходящий элемент. Пробелы по краям удаляются, а пустое значение означает отсутствие ожидания. Элемент при этом не обязательно видим. Ожидание селектора ограничено 30 секундами.

{
  "url": "https://example.com",
  "waitForSelector": ".dashboard-ready"
}

waitForSelector и selector решают разные задачи: первое поле определяет, когда страница готова, второе — какой видимый элемент попадёт в изображение. Их можно использовать вместе.

Порядок выполнения

В автоматическом режиме порядок такой: изолированный контекст Chromium с размером экрана → новая страница → навигация до загрузки HTML → короткое ожидание сетевого покоя → ожидание waitForSelector → задержка → скрытие всех совпадений hideSelectors → поиск видимого элемента по selector, если он задан → снимок или PDF. В явном режиме автоматическое ожидание сетевого покоя заменяется ожиданием выбранного события. После скрытия элементов дополнительное ожидание сетевого покоя не запускается.

{
  "url": "https://example.com",
  "viewportWidth": 1440,
  "viewportHeight": 900,
  "waitUntil": "domcontentloaded",
  "waitForSelector": "[data-render-complete]",
  "delayMs": 500
}

Снимок элемента и настройки готовности поддерживаются только в Chromium. Навигация ограничена 30 секундами, ожидание селектора и создание снимка — 30 секундами на действие, а автоматический совместимый режим использует прежнее дополнительное ожидание сетевого покоя до 5 секунд. Пользовательский JavaScript или отдельный тайм-аут передать нельзя.

Примеры ошибок

Некорректный запрос отклоняется до создания задачи и расходования квоты. Ошибка синтаксиса CSS классифицируется безопасно во время проверки в Chromium. NAVIGATION_TIMEOUT означает тайм-аут навигации, WAIT_SELECTOR_TIMEOUT — тайм-аут ожидания элемента, а RENDER_TIMEOUT сохраняется для совместимой классификации тайм-аута снимка или отмены выполнения:

Без схемы: example.com
Локальный адрес: http://127.0.0.1
Неподдерживаемый браузер: opera
Неподдерживаемый формат: gif
Нецелое качество или значение вне диапазона 1–100: INVALID_IMAGE_QUALITY
imageQuality с PNG или PDF: IMAGE_QUALITY_FORMAT_CONFLICT
WebP с браузером, отличным от Chromium: WEBP_BROWSER_UNSUPPORTED
Неизвестное событие загрузки: INVALID_WAIT_UNTIL
Отрицательная или дробная задержка в миллисекундах: INVALID_DELAY
Задержка больше 15000 мс: DELAY_TOO_LARGE
Селектор длиннее 256 символов: WAIT_SELECTOR_TOO_LONG
Некорректный CSS-селектор: INVALID_WAIT_SELECTOR
Некорректное поле hideSelectors: INVALID_HIDE_SELECTORS
Больше 10 скрываемых селекторов: TOO_MANY_HIDE_SELECTORS
Скрываемый селектор длиннее 256 символов: HIDE_SELECTOR_TOO_LONG
Общая длина скрываемых селекторов больше 1024 символов: HIDE_SELECTORS_TOO_LARGE
Пустой или содержащий управляющие символы скрываемый селектор: INVALID_HIDE_SELECTOR
Элемент не появился вовремя: WAIT_SELECTOR_TIMEOUT
Пустой или некорректный селектор снимка: INVALID_CAPTURE_SELECTOR
Селектор снимка длиннее 256 символов: CAPTURE_SELECTOR_TOO_LONG
selector вместе с fullPage=true: SELECTOR_FULL_PAGE_CONFLICT
Элемент для снимка не найден: CAPTURE_SELECTOR_NOT_FOUND
Элемент найден, но не виден: CAPTURE_SELECTOR_NOT_VISIBLE
Область элемента слишком велика: CAPTURE_REGION_TOO_LARGE
PDF нельзя сочетать с selector: PDF_SELECTOR_CONFLICT
PDF нельзя сочетать с fullPage=true: PDF_FULL_PAGE_CONFLICT
PDF нельзя сочетать с deviceScaleFactor=2: PDF_DEVICE_SCALE_CONFLICT
Документ слишком длинный: PDF_DOCUMENT_TOO_LARGE
PDF превышает лимит размера: PDF_OUTPUT_TOO_LARGE
PDF не удалось создать: PDF_RENDER_FAILED

Полный сценарий создания задачи описан в руководстве по асинхронному API. Получение изображения в том же запросе — в руководстве по синхронному API.