Снимите публичную страницу.

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

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

Authorization: Bearer <access_token>

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

{ "error": "Unauthorized" }

Параметры запроса и JSON-поля с именем access_token игнорируются. Храните токен как пароль. Тот, у кого он есть, может читать снимки этого аккаунта.

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

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, если параметр ниже не говорит иначе.

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

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"
}

Неудачный снимок содержит 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 по-прежнему можно заменить.

Параметры

Параметры — это 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 и другие межузловые имена отклоняются.

Источник

Страница

Окно

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

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

Блокировка

Запрос

CSS и JavaScript

Изображение

PDF

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

Кэш и вебхук

Ошибки

{
  "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 и get_screenshot. create_screenshot принимает те же поля, что POST /api/v1/screenshots, плюс wait_seconds. Ожидание по умолчанию — 25 секунд и не может быть больше 45. 0 возвращает задачу, как только она поставлена в очередь. Снимок из кэша возвращается сразу.

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

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