Документация API — ScreenshotOne.ru

Обзор

Протокол: HTTPS (рекомендуется) или HTTP
Метод: GET
Авторизация: не требуется (MVP)
Кодировка URL: параметр url передавайте в закодированном виде

GET /api/v1/screenshot

Загружает указанную страницу в headless-браузере и возвращает скриншот.

GET /api/v1/screenshot?url=https://example.com&full_page=true&dpi=150&delay=3&format=png

Успешный ответ: бинарное тело (изображение или PDF) с заголовком Content-Type.

Параметры запроса

Параметр	Тип	По умолчанию	Описание
`url`	string	—	Обязательный. Адрес страницы (`http://` или `https://`). Приватные IP и localhost запрещены.
`full_page`	boolean	`true`	Скриншот всей прокручиваемой страницы. `false` — только viewport.
`width`	integer	`1280`	Ширина viewport, 320–3840 px.
`height`	integer	`720`	Высота viewport, 240–2160 px.
`format`	string	`png`	Формат: `png`, `jpeg` (или `jpg`), `pdf`.
`dpi`	integer	`150`	Плотность растра: `100`, `150`, `300`, `600`. Не применяется к PDF.
`delay`	integer	`3`	Пауза после загрузки страницы, 0–15 секунд. Полезно для SPA.

Коды ответа

Код	Описание
`200`	Успех. Тело — PNG, JPEG или PDF.
`400`	Некорректный URL или параметры (JSON с описанием).
`429`	Превышен лимит: 1 запрос в минуту с IP. Заголовок `Retry-After`.
`502`	Страница не загрузилась или ошибка рендера.
`504`	Таймаут загрузки (до 45 с).

Заголовки ответа при успехе:

Content-Type — image/png, image/jpeg или application/pdf
Content-Disposition — inline; filename="screenshot.png"
X-ScreenshotOne-IP-Limit — 1/min

Формат ошибки

При ошибках (кроме 200) возвращается JSON:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Лимит: 1 скриншот в минуту с одного IP. Повторите через 42 с."
  }
}

Коды error.code: invalid_request, rate_limit_exceeded, timeout, render_failed.

Лимиты и ограничения

1 скриншот в минуту с одного IP-адреса.
Таймаут навигации: до 45 секунд.
Не обходим капчу, Cloudflare challenge и anti-bot.
SSRF-защита: запрещены localhost, приватные сети, редиректы на внутренние адреса.

Безопасность URL

Сервис открывает переданный адрес в изолированном headless-браузере. Чтобы защитить сервер от злоупотреблений:

Разрешены только http:// и https://.
Блокируются приватные IP, localhost, облачные metadata-адреса, локальные домены (.local, .internal).
DNS проверяется до загрузки страницы; подзапросы и редиректы фильтруются.
URL с логином/паролем (user:pass@host) отклоняются.

Не передавайте в URL секреты, токены и персональные данные — они могут попасть в логи и архив диагностики.

Замечания по безопасности: форма обратной связи.

Примеры

cURL — PNG, вся страница

curl -G "https://screenshotone.ru/api/v1/screenshot" \
  --data-urlencode "url=https://example.com" \
  --data-urlencode "full_page=true" \
  --data-urlencode "dpi=150" \
  --data-urlencode "delay=3" \
  -o screenshot.png

cURL — PDF

curl -G "https://screenshotone.ru/api/v1/screenshot" \
  --data-urlencode "url=https://example.com" \
  --data-urlencode "format=pdf" \
  -o screenshot.pdf

JavaScript (fetch)

const params = new URLSearchParams({
  url: 'https://example.com',
  full_page: 'true',
  dpi: '150',
  format: 'png',
});

const res = await fetch(`https://screenshotone.ru/api/v1/screenshot?${params}`);
if (!res.ok) throw new Error(await res.text());
const blob = await res.blob();
// blob — изображение

Python

import requests

r = requests.get(
    "https://screenshotone.ru/api/v1/screenshot",
    params={
        "url": "https://example.com",
        "full_page": "true",
        "dpi": 150,
        "format": "png",
    },
    timeout=60,
)
r.raise_for_status()
with open("screenshot.png", "wb") as f:
    f.write(r.content)

HTML (прямая ссылка)

<img
  src="https://screenshotone.ru/api/v1/screenshot?url=https://example.com&format=png"
  alt="Скриншот example.com"
/>

GET /api/v1/health

Проверка состояния API. Ответ JSON:

{
  "status": "ok",
  "service": "screenshotone-api",
  "redis": true
}

status: "degraded" — Redis недоступен, rate limit может не работать.

См. также: как сделать скриншот через API · API vs Puppeteer