Справка по API

Документация API скриншотов сайта

Отправьте URL, HTML или Markdown. Site2image вернёт PNG, JPG, WebP, PDF, HTML или Markdown. Создание ставит задачу в очередь. Опросите подписанный URL файла, задайте вебхук или используйте URL для встраивания, когда тег изображения должен показать снимок.

Примеры на этой странице используют https://site2image.ru. Токен работает только на сайте, который его выдал.

Аутентификация

Передайте токен доступа со страницы аккаунта в заголовке Authorization:

Authorization: Bearer <access_token>

Токен обязателен в каждом запросе. Отсутствующий, неверный или неизвестный токен возвращает 401:

{ "error": "Unauthorized" }

Создание, пакетное создание и оба маршрута встраивания также требуют действующий тариф. Верный токен аккаунта без тарифа или с истёкшим тарифом возвращает 402:

{ "error": "An active plan is required" }

Параметры запроса и JSON-поля с именем access_token игнорируются, кроме GET /api/v1/screenshots/embed и GET /api/v1/screenshots/:id/embed. Храните токен как пароль. Тот, у кого он есть, может читать снимки этого аккаунта.

Создать снимок

POST /api/v1/screenshots

Отправьте ровно одно из url, html или markdown. format по умолчанию PNG и также принимает JPG, JPEG, WEBP, PDF, HTML, MD и MARKDOWN. JPEG сохраняется как JPG. MARKDOWN сохраняется как MD. callback_url необязателен.

curl -X POST https://site2image.ru/api/v1/screenshots \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "format": "PNG",
    "viewport_device": "iphone_14",
    "block_cookie_banners": true,
    "callback_url": "https://client.example.com/hooks/screenshots"
  }'

Новая задача возвращает 202 Accepted. Идентификатор — UUID. image_url отсутствует, пока вы не запросите снимок и статус не станет ready.

{
  "id": "3f1c0a6e-8b24-4d5a-9c17-2e6b0d4a8f31",
  "status": "pending",
  "url": "https://example.com",
  "format": "PNG",
  "created_at": "2026-01-01T12:00:00Z"
}

Отправленные параметры возвращаются в задаче после применения пресета устройства. Снимок с viewport_device равным iphone_14 также сохраняет ширину, высоту, масштаб и user agent этого устройства.

HTML ограничен 500 000 байтами. Markdown ограничен 200 000 байтами. url или callback_url должен быть абсолютным http- или https-адресом публичного интернета длиной не более 2048 символов. Localhost, имена .local и частные, loopback или link-local адреса возвращают 422 с подробностью "is not allowed".

Снимок ждёт, пока сеть утихнет, и затем снимает всю страницу в 1440×900, если параметр ниже не говорит иначе.

Создать снимки пакетом

POST /api/v1/screenshots/bulk

Отправьте JSON-массив запросов снимков. В каждом объекте обязателен только url. Остальные поля совпадают с POST /api/v1/screenshots, включая format, callback_url и параметры ниже.

curl -X POST https://site2image.ru/api/v1/screenshots/bulk \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "url": "https://example.com",
      "file_type": "png",
      "width": 1440,
      "height": 900,
      "fresh": true
    },
    {
      "url": "https://example.com/pricing",
      "format": "jpg",
      "viewport_width": 1280,
      "viewport_height": 900,
      "callback_url": "https://client.example.com/hooks/screenshots"
    }
  ]'

file_type задаёт format. width и height задают viewport_width и viewport_height. fresh: true снимает заново. fresh: false — это cache: true. Если переданы и короткое имя, и полное поле, используется полное поле.

Ответ — JSON-массив тех же объектов, что возвращает одиночное создание, в том же порядке. Новая работа возвращает 202 Accepted. Когда каждый элемент — снимок из кэша, ответ 200 OK.

[
  {
    "id": "3f1c0a6e-8b24-4d5a-9c17-2e6b0d4a8f31",
    "status": "pending",
    "url": "https://example.com",
    "format": "PNG",
    "created_at": "2026-01-01T12:00:00Z",
    "options": {
      "viewport_width": 1440,
      "viewport_height": 900
    }
  }
]

Отправьте Content-Type: text/csv, чтобы передать тот же пакет как CSV и получить CSV. Первая строка — заголовок. url обязателен. Остальные столбцы — те же поля, что в JSON, включая file_type, width, height, fresh и callback_url. Пробелы вокруг запятых игнорируются. Заголовок ответа — id,url. url — адрес страницы, сохранённый для этого снимка. Новый пакет возвращает 202. Когда каждая строка — снимок из кэша, ответ 200. Неверный CSV или неверная строка возвращают JSON 422 и ничего не создают.

curl -X POST https://site2image.ru/api/v1/screenshots/bulk \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: text/csv" \
  --data-binary @screenshots.csv
url,file_type,width,height,fresh
https://example.com,png,1200,800,true
https://example.com/pricing,jpg,1920,1080,false
id,url
3f1c0a6e-8b24-4d5a-9c17-2e6b0d4a8f31,https://example.com
6b2d1c7f-9c35-4e6b-8d28-3f7c1e5b9a42,https://example.com/pricing

Задайте callback_url у элемента, и Site2image отправит этот снимок методом POST, когда его статус станет ready. Каждый элемент доставляется отдельно. Сбой вебхука оставляет этот снимок ready.

Один запрос принимает не больше 50 снимков. Пустой массив, тело, которое не является массивом, или любой неверный элемент возвращают 422 и ничего не создают. Ключ в details — индекс элемента. Пакет, который превысит месячный лимит тарифа или лимит в минуту, возвращает 429 и ничего не создаёт.

Встроить снимок

GET /api/v1/screenshots/embed

Этот запрос снимает страницу до ответа и возвращает сам файл. Поместите URL в тег img. Параметры запроса — те же поля, что у POST /api/v1/screenshots. format по умолчанию PNG и также принимает JPG, WEBP и PDF.

<img
  src="https://site2image.ru/api/v1/screenshots/embed?url=https%3A%2F%2Fexample.com&access_token=<access_token>&format=jpg"
  alt="example.com">
curl "https://site2image.ru/api/v1/screenshots/embed?url=https%3A%2F%2Fexample.com&access_token=<access_token>&format=jpg" \
  --output screenshot.jpg

Закодируйте адрес страницы. Запрос к https://example.com использует url=https%3A%2F%2Fexample.com. Вызов ждёт окончания съёмки и затем возвращает файл.

Передайте access_token в строке запроса. Тег изображения не может задать заголовок Authorization. Заголовок bearer тоже принимается. Токен виден в исходном коде страницы, поэтому любой, кто видит тег, может создавать снимки этого аккаунта.

Кэш включён, если не передать cache=false. Тот же URL, формат и параметры повторно отдают последний готовый снимок за cache_ttl секунд. Окно по умолчанию — 4 часа. Ответ приватный, поэтому общий кэш его не хранит.

Отсутствующий или неизвестный токен возвращает 401 и JSON. Верный токен без действующего тарифа возвращает 402 и JSON. Новый снимок сверх месячного лимита или лимита в минуту возвращает 429 и JSON. Неверный URL или неудачный снимок возвращает 422 и JSON. Временная ошибка съёмки возвращает 503 и JSON. Готовый снимок возвращает файл с типом вроде image/png, image/jpeg или image/webp.

Готовый снимок можно встроить и по идентификатору. Параметр access_token обязателен в GET /api/v1/screenshots/:id/embed. Запрос перенаправляет на сохранённые PNG, JPG или WEBP этого аккаунта, и тег изображения загружает файл из хранилища. Заголовок bearer тоже принимается. Отсутствующий или неизвестный токен возвращает 401. Верный токен без действующего тарифа возвращает 402. Чужой или отсутствующий идентификатор, неготовый снимок, а также PDF, HTML и Markdown возвращают JSON 404.

<img
  src="https://site2image.ru/api/v1/screenshots/3f1c0a6e-8b24-4d5a-9c17-2e6b0d4a8f31/embed?access_token=<access_token>"
  alt="example.com">

Получить снимок

GET /api/v1/screenshots/:id

curl https://site2image.ru/api/v1/screenshots/3f1c0a6e-8b24-4d5a-9c17-2e6b0d4a8f31 \
  -H "Authorization: Bearer <access_token>"

Снимок должен принадлежать аутентифицированному аккаунту. Идентификатор другого аккаунта или идентификатор, который не является UUID, возвращает 404 с { "error": "Not Found" }.

status переходит из pending в processing, затем в ready или failed. image_url остаётся null, пока статус не станет ready. Готовый снимок содержит подписанный URL запрошенного формата. Этот URL истекает через 300 секунд. Запросите снимок снова, когда нужна новая ссылка.

{
  "id": "3f1c0a6e-8b24-4d5a-9c17-2e6b0d4a8f31",
  "status": "ready",
  "url": "https://example.com",
  "format": "PNG",
  "created_at": "2026-01-01T12:00:00Z",
  "image_url": "https://signed.example/screenshot.png",
  "error_message": null,
  "updated_at": "2026-01-01T12:00:08Z"
}

Запросите /api/v1/screenshots/:id.csv, чтобы получить те же поля, что в этом JSON-ответе, одной строкой CSV. Заголовок — имена полей. Пустое значение — пустая ячейка. options, metadata и slices записываются в свою ячейку как JSON, когда этот ответ их содержит. Отсутствующий или чужой идентификатор по-прежнему возвращает JSON 404.

curl https://site2image.ru/api/v1/screenshots/3f1c0a6e-8b24-4d5a-9c17-2e6b0d4a8f31.csv \
  -H "Authorization: Bearer <access_token>"
id,status,url,format,created_at,image_url,error_message,updated_at
3f1c0a6e-8b24-4d5a-9c17-2e6b0d4a8f31,ready,https://example.com,PNG,2026-01-01T12:00:00Z,https://signed.example/screenshot.png,,2026-01-01T12:00:08Z

Неудачный снимок содержит error_message со значением "The page could not be captured.", а image_url равен null. Если вы просили метаданные или срезы, эти поля появляются в ответе, когда снимок завершён.

Скачать снимок

GET /api/v1/screenshots/:id/download

Когда снимок ready, этот маршрут перенаправляет на короткоживущий подписанный URL. Тот же запрос до готовности файла или идентификатор другого аккаунта возвращает 404.

Устройства

GET /api/v1/devices

Передайте id как viewport_device. Пресет задаёт окно, плотность пикселей, касание и user agent. viewport_width, viewport_height и device_scale_factor по-прежнему можно заменить.

ИдентификаторЭкран
iphone_se iPhone SE · 375×667 · масштаб 2
iphone_13 iPhone 13 · 390×844 · масштаб 3
iphone_13_landscape iPhone 13 landscape · 844×390 · масштаб 3
iphone_13_pro_max iPhone 13 Pro Max · 428×926 · масштаб 3
iphone_13_pro_max_landscape iPhone 13 Pro Max landscape · 926×428 · масштаб 3
iphone_14 iPhone 14 · 390×844 · масштаб 3
iphone_14_landscape iPhone 14 landscape · 844×390 · масштаб 3
iphone_14_pro_max iPhone 14 Pro Max · 430×932 · масштаб 3
iphone_14_pro_max_landscape iPhone 14 Pro Max landscape · 932×430 · масштаб 3
pixel_7 Pixel 7 · 412×915 · масштаб 2.625
pixel_7_landscape Pixel 7 landscape · 915×412 · масштаб 2.625
galaxy_s9+ Galaxy S9+ · 360×740 · масштаб 3
galaxy_s9+_landscape Galaxy S9+ landscape · 740×360 · масштаб 3
ipad iPad · 768×1024 · масштаб 2
ipad_landscape iPad landscape · 1024×768 · масштаб 2
ipad_pro iPad Pro · 1024×1366 · масштаб 2
ipad_pro_landscape iPad Pro landscape · 1366×1024 · масштаб 2

Параметры

Параметры — это JSON-поля запроса POST /api/v1/screenshots. Неизвестное поле возвращает 422. Логические значения — true или false.

Cookie — это объекты с name, value, domain, path, secure, http_only и same_site либо строки вроде name=value; Domain=example.com; Secure. Домен должен быть целевым хостом, поэтому для cookie нужен url. same_site равен Lax, Strict или None. Заголовки — это словарь или список строк "Name: value". Host, Connection и другие межузловые имена отклоняются.

Источник

html строка · до 500 000 байт HTML вместо URL. Не больше 500 КБ. Отправьте одно из url, html или markdown.
markdown строка · до 200 000 байт Markdown вместо URL. Не больше 200 КБ. Отправьте одно из url, html или markdown.

Страница

full_page логический · по умолчанию true Снимает всю страницу. false снимает только окно.
full_page_scroll логический · по умолчанию как у full_page Прокручивает вниз, чтобы подгрузился отложенный контент. Следует значению full_page.
full_page_scroll_delay целое · 0–10000 Пауза между шагами прокрутки, в миллисекундах.
full_page_scroll_by целое · 50–5000 Шаг прокрутки в пикселях.
full_page_max_height целое · 1–30000 Максимальная высота всей страницы в пикселях.
full_page_algorithm строка default или by_sections, если доступен libvips.
full_page_slices логический · по умолчанию false Также сохраняет вертикальные срезы полностраничного PNG, JPG или WebP.
full_page_slice_height целое · по умолчанию 4000 · 100–16000 Высота среза в пикселях.
full_page_slice_overlap_height целое · по умолчанию 0 · 0–16000 Перекрытие срезов в пикселях.
capture_beyond_viewport логический · по умолчанию true Включает содержимое за пределами окна при полном снимке.

Окно

viewport_device строка Пресет устройства. Вызовите list_devices, чтобы увидеть идентификаторы.
viewport_width целое · по умолчанию 1440 · 1–3840 Ширина CSS-окна в пикселях.
viewport_height целое · по умолчанию 900 · 1–16384 Высота CSS-окна в пикселях.
device_scale_factor число · по умолчанию 1 · 1.0–5.0 Плотность пикселей устройства, от 1 до 5.
viewport_mobile логический Эмулирует мобильное окно.
viewport_has_touch логический Эмулирует сенсорный экран.
viewport_landscape логический Меняет ширину и высоту местами, когда окно портретное.
dark_mode логический Ставит prefers-color-scheme в тёмную тему при true и в светлую при false.
reduced_motion логический Эмулирует prefers-reduced-motion.
reduce_motion логический Эмулирует prefers-reduced-motion и останавливает анимации.
media_type строка Эмулируемый тип носителя: screen или print.

Элемент и область

selector строка · до 500 байт CSS-селектор, который снимается.
selector_algorithm строка default или clip, чтобы снять элемент как прямоугольник.
selector_scroll_into_view логический · по умолчанию true Прокручивает селектор в видимую область перед снимком.
error_on_selector_not_found логический · по умолчанию true, если задан selector Завершается ошибкой, если selector ничего не находит.
clip_x целое · 0–20000 Левый край прямоугольника обрезки, в пикселях.
clip_y целое · 0–30000 Верхний край прямоугольника обрезки, в пикселях.
clip_width целое · 1–20000 Ширина обрезки в пикселях. Отправьте все четыре поля обрезки вместе.
clip_height целое · 1–30000 Высота обрезки в пикселях. Отправьте все четыре поля обрезки вместе.

Ожидание и действия

wait_until список строк · load, domcontentloaded, networkidle0, networkidle2 События навигации, которых нужно дождаться, например load или networkidle0.
wait_for_selector строка · до 500 байт CSS-селектор, которого нужно дождаться.
wait_for_selector_algorithm строка at_least_one или at_least_by_count.
delay число · 0.0–60.0 Сколько секунд ждать после готовности страницы.
timeout целое · 1–120 Сколько секунд ждать страницу и селекторы.
navigation_timeout целое · 1–60 Сколько секунд ждать навигацию.
click строка · до 500 байт CSS-селектор, по которому выполняется щелчок перед снимком.
hover строка · до 500 байт CSS-селектор, на который наводится указатель перед снимком.
scroll_into_view строка · до 500 байт CSS-селектор, который прокручивается в видимую область.
scroll_into_view_adjust_top целое · по умолчанию 0 · -2000–2000 Сдвиг в пикселях после прокрутки элемента в видимую область.
error_on_click_selector_not_found логический · по умолчанию true Завершается ошибкой, если click ничего не находит.
error_on_hover_selector_not_found логический · по умолчанию true Завершается ошибкой, если hover ничего не находит.

Блокировка

block_cookie_banners логический Скрывает обычные баннеры cookie.
block_banners_by_heuristics логический Скрывает баннеры, найденные эвристикой.
block_ads логический Блокирует обычные рекламные запросы.
block_trackers логический Блокирует обычные запросы трекеров.
block_chats логический Блокирует виджеты чата.
block_requests список строк Шаблоны URL, которые блокируются.
block_resources список строк · document, stylesheet, image, media, font, script, texttrack, xhr, fetch, eventsource, websocket, manifest, other Типы ресурсов, которые блокируются, например image или script.
hide_selectors список строк CSS-селекторы, которые скрываются.

Запрос

user_agent строка · до 500 байт User agent браузера.
headers объект или список Дополнительные заголовки запроса. Словарь имени и значения или список строк "Name: value".
cookies список Cookie целевого хоста. Объекты с name и value или строки name=value; Domain=host.
authorization строка · до 1 024 байт Значение заголовка Authorization, отправляемого странице.
time_zone строка Часовой пояс IANA, например America/New_York.
bypass_csp логический Обходит Content-Security-Policy страницы.
geolocation_latitude число · -90.0–90.0 Широта, видимая странице. Отправьте и долготу.
geolocation_longitude число · -180.0–180.0 Долгота, видимая странице. Отправьте и широту.
geolocation_accuracy число · по умолчанию 100, если задана геолокация · 0.0–100000.0 Точность геолокации в метрах.
ignore_host_errors логический Продолжает, если основная навигация вернула ошибочный HTTP-статус.

CSS и JavaScript

styles строка · до 100 000 байт CSS, который добавляется на страницу.
scripts строка · до 50 000 байт JavaScript, который выполняется перед снимком.
scripts_wait_until список строк · load, domcontentloaded, networkidle0, networkidle2 События, которых нужно дождаться после скриптов. Обязательно, если скрипт меняет location.

Изображение

image_quality целое · 0–100 Качество JPEG или WebP от 0 до 100.
image_width целое · 1–10000 Масштабирует PNG, JPG или WebP до этой ширины.
image_height целое · 1–10000 Масштабирует PNG, JPG или WebP до этой высоты.
omit_background логический Прозрачный фон. Только PNG.

PDF

pdf_paper_format строка · letter, legal, tabloid, ledger, a0, a1, a2, a3, a4, a5, a6 Размер страницы PDF, например a4 или letter.
pdf_landscape логический Использует альбомную страницу PDF.
pdf_fit_one_page логический Умещает снимок на одну страницу PDF.
pdf_print_background логический · по умолчанию true Печатает фоны CSS. Для PDF по умолчанию true.
pdf_margin строка Поле со всех сторон, например 0, 20px, 10mm или 0.5in.
pdf_margin_top строка Верхнее поле PDF, например 20px, 10mm или 0.5in.
pdf_margin_right строка Правое поле PDF, например 20px, 10mm или 0.5in.
pdf_margin_bottom строка Нижнее поле PDF, например 20px, 10mm или 0.5in.
pdf_margin_left строка Левое поле PDF, например 20px, 10mm или 0.5in.

Метаданные и проверки

metadata_page_title логический Добавляет заголовок страницы в метаданные.
metadata_image_size логический Добавляет размер изображения в метаданные.
metadata_http_response_status_code логический Добавляет HTTP-статус в метаданные.
metadata_fonts логический Добавляет шрифты в метаданные.
metadata_open_graph логический Добавляет теги Open Graph в метаданные.
metadata_icon логический Добавляет значок страницы в метаданные.
metadata_content логический Добавляет содержимое страницы в метаданные.
metadata_content_format строка Формат содержимого в метаданных: html, text или markdown.
fail_if_content_contains список строк Завершается ошибкой, если текст страницы содержит любую из этих строк.
fail_if_content_missing список строк Завершается ошибкой, если в тексте страницы нет любой из этих строк.

Кэш и вебхук

cache логический Возвращает недавний готовый снимок с тем же URL, форматом и параметрами.
cache_ttl целое · по умолчанию 14400 секунд · 60–2592000 Сколько секунд кэшированный снимок можно использовать снова.
cache_key строка · до 200 байт Ваш ключ кэша, сохраняемый вместе с запросом.
external_identifier строка · до 128 байт Ваш идентификатор, сохраняемый вместе с запросом.
webhook_sign логический Подписывает тело вебхука как HMAC-SHA256 токеном доступа.

Ошибки

СтатусКогда
401 { "error": "Unauthorized" }, если bearer-токен отсутствует или неизвестен.
402 { "error": "An active plan is required" }, если токен верен, а у аккаунта нет действующего тарифа. Это возвращают создание, пакетное создание и оба маршрута встраивания.
429 { "error": "Monthly screenshot limit reached", "details": { "limit": 2000, "used": 2000 } }, если этот запрос превысит месячный лимит тарифа. Это возвращают создание, пакетное создание и встраивание, которого нет в кэше. used — счётчик до этого запроса. resets_at — момент, когда лимит снова откроется.
429 { "error": "Per-minute screenshot limit reached", "details": { "limit": 30, "used": 30 } }, если этот запрос превысит число снимков тарифа в минуту. Окно длится 60 секунд с первого засчитанного снимка и не сдвигается вперёд. Это возвращают создание, пакетное создание и встраивание, которого нет в кэше.
404 { "error": "Not Found" }, если идентификатор неизвестен, принадлежит другому аккаунту или файл ещё не готов к скачиванию.
422 Проверка не прошла. details сопоставляет каждому полю список сообщений.
500 { "error": "Internal Server Error" }. Ответ не содержит текст исключения.
{
  "error": "Validation failed",
  "details": {
    "url": ["must be a valid HTTP or HTTPS URL"]
  }
}

Вебхуки

Если задан callback_url, готовый снимок доставляется методом POST с Content-Type: application/json. Ответ 2xx завершает доставку. Сбои сети и HTTP 5xx повторяются. Неудачный вебхук оставляет снимок ready без изменений.

{
  "id": "3f1c0a6e-8b24-4d5a-9c17-2e6b0d4a8f31",
  "status": "ready",
  "url": "https://example.com",
  "format": "PNG",
  "image_url": "https://signed.example/screenshot.png"
}

Установите webhook_sign в true, и запрос будет содержать X-Site2image-Signature: sha256=.... Значение — HMAC-SHA256 исходного тела, ключ — ваш токен доступа.

Кэш

Отправьте "cache": true, чтобы повторно использовать последний снимок ready с тем же URL, форматом и параметрами за последние секунды cache_ttl. Окно по умолчанию — 4 часа. Попадание возвращает 200 OK и готовый снимок, включая image_url, и не ставит новую задачу в очередь.

MCP

Ассистенты используют тот же API снимков по Streamable HTTP.

POST https://site2image.ru/mcp
Authorization: Bearer <access_token>
Content-Type: application/json
Accept: application/json, text/event-stream

Cursor и другие удалённые клиенты MCP принимают URL и заголовок bearer:

{
  "mcpServers": {
    "site2image": {
      "url": "https://site2image.ru/mcp",
      "headers": {
        "Authorization": "Bearer <access_token>"
      }
    }
  }
}

tools/list возвращает list_devices, create_screenshot, create_screenshots и get_screenshot. create_screenshot принимает те же поля, что POST /api/v1/screenshots, плюс wait_seconds. Ожидание по умолчанию — 25 секунд и не может быть больше 45. 0 возвращает задачу, как только она поставлена в очередь. Снимок из кэша возвращается сразу. create_screenshots принимает массив screenshots из тех же полей, не больше 50 элементов. Его wait_seconds по умолчанию равен 0 и общий для всего пакета.

create_screenshot и get_screenshot возвращают тот же JSON, что GET /api/v1/screenshots/:id. Готовые PNG, JPG или WebP размером не более 1 МБ также возвращаются как изображение. HTML и Markdown размером не более 100 КБ также возвращаются как текст. PDF и более крупные файлы остаются в image_url. create_screenshots возвращает этот JSON массивом, в порядке запроса, без файлов.

GET, PUT, PATCH и DELETE на /mcp возвращают 405. Уведомление вроде notifications/initialized возвращает 202 с пустым телом.