API Документация

1. Зарегистрируйтесь бесплатно и создайте ключ на странице «API Key» в консоли.
2. Передайте ключ в заголовке X-Access-Key и вызовите метод создания скриншота:

curl "https://glanceshot.com/v1/screenshot?url=https://example.com&full_page=true" \
  -H "X-Access-Key: $GLANCESHOT_KEY" \
  -o screenshot.png

Каждый запрос требует API Key. Передать его можно любым из способов:

• Заголовок X-Access-Key: gls_… (рекомендуется для серверных запросов)
• Параметр запроса access_key=gls_… (только для вызовов с сервера, не размещайте его на веб-страницах)
• Подписанный URL (если URL нужно разместить на веб-странице — API Key и секрет останутся скрыты)

API Key показывается в открытом виде только один раз — при создании. Сохраните его в надёжном месте. При утечке ключ можно отключить в консоли.

Параметры только для скриншотов:

Общие параметры для скриншотов и PDF:

Скриншоты одностраничных приложений (React, Vue и др.):Перед созданием скриншота страница выполняет JavaScript в настоящем браузере. По умолчанию networkidle ждёт завершения загрузки данных. Если после этого контент появляется по таймеру или после анимации, укажите в wait_for_selector элемент, означающий готовность контента. Если подходящего элемента нет, добавьте время ожидания через delay.

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

curl -X POST "https://glanceshot.com/v1/pdf" \
  -H "X-Access-Key: $GLANCESHOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"html": "<h1>Квартальный отчёт</h1><p>Основной текст…</p>", "paper": "a4"}' \
  -o report.pdf

По умолчанию (response_type=binary) файл возвращается напрямую, а Content-Type соответствует его формату. Заголовки ответа:

• X-Request-Id: ID запроса — укажите его при обращении в поддержку
• X-Glanceshot-Cache: HIT или MISS
• X-Glanceshot-Truncated: true: скриншот всей страницы обрезан из-за превышения высоты 20,000 пикселей
• X-Glanceshot-Format-Changed: webp: PNG размером более 5 MB автоматически преобразован в WebP (при явном указании format=png преобразование не выполняется)

При response_type=json возвращаются адрес файла и метаданные:

curl -X POST "https://glanceshot.com/v1/screenshot" \
  -H "X-Access-Key: $GLANCESHOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "response_type": "json"}'

# Возвращает
{
  "url": "https://glanceshot.com/i/3f/3f9c….png",
  "cache_hit": false,
  "duration_ms": 1284,
  "format": "png",
  "width": 1280,
  "height": 800,
  "request_id": "req_01j…"
}

Хотите вставить URL скриншота прямо в <img src>, не раскрывая API Key? Подписанный URL содержит только публичный key_id, без API Key. Подпись вычисляется на вашем сервере с помощью секрета, соответствующего ключу. ID ключа и секрет доступны в консоли на странице API Key:

canonical = Отсортируйте все параметры, кроме signature, в лексикографическом порядке по имени.
            Представьте каждый параметр как k=urlencode(v) (RFC 3986, пробел кодируется как %20) и соедините через &
signature = hex(HMAC-SHA256(secret, canonical))

Корректная подпись подтверждает авторизацию. Запросы без подписи или с неверной подписью отклоняются. Изменение любого параметра (например, url) делает подпись недействительной. Необязательный параметр expires (в секундах Unix) участвует в подписи; после истечения срока возвращается signature_expired. Чтобы обновить кеш, измените любой незначащий параметр (например, v=2) и заново подпишите URL. Подписанные URL поддерживают только GET-запросы к API скриншотов и PDF; параметры прокси не поддерживаются.

key_id — публичный идентификатор, одного его недостаточно для вызова API. Не добавляйте API Key (access_key) в подписанный URL: такой запрос сразу вернёт invalid_params. Если вы уже размещали API Key на веб-странице, отключите этот ключ в консоли и создайте новый.

import crypto from "node:crypto";

// Кодирование по RFC 3986 (пробел — %20) должно соответствовать правилам сервера
const enc = (v) =>
  encodeURIComponent(v).replace(/[!'()*]/g, (c) => "%" + c.charCodeAt(0).toString(16).toUpperCase());

function signedUrl(params, keyId, secret) {
  const all = { ...params, key_id: keyId };
  const canonical = Object.keys(all).sort().map((k) => `${k}=${enc(String(all[k]))}`).join("&");
  const signature = crypto.createHmac("sha256", secret).update(canonical).digest("hex");
  return `https://glanceshot.com/v1/screenshot?${canonical}&signature=${signature}`;
}

const src = signedUrl({ url: "https://example.com", viewport_width: 1200 }, KEY_ID, SECRET);
// <img src={src} alt="Предпросмотр веб-страницы" />

Если нужно открыть страницу из определённой страны или региона (например, чтобы проверить местный язык, контент или цены), укажите в запросе собственный платный прокси. Расходы на прокси вы оплачиваете самостоятельно. Страница, её изображения, скрипты и запросы к API будут загружаться через этот прокси. Поддерживаются прокси socks5:// и http://, в том числе с именем пользователя и паролем.

curl -X POST "https://glanceshot.com/v1/screenshot" \
  -H "X-Access-Key: $GLANCESHOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "proxy": "socks5://user:pass@203.0.113.10:1080"}' \
  -o screenshot.png

• proxy можно передавать только в теле POST-запроса. Он недоступен для GET-запросов, подписанных URL и пакетных задач, чтобы учётные данные прокси не попадали в URL, историю браузера или на веб-страницы.
• Если имя пользователя или пароль содержат специальные символы, такие как @ или :, их нужно предварительно закодировать для URL (например, заменить @ на %40).
• Запросы с прокси кешируются отдельно: их результаты не используются для запросов без прокси или с другим прокси.
• Если не удалось подключиться к прокси, пройти аутентификацию или открыть целевой сайт, возвращается proxy_failed. Такие запросы не оплачиваются. Конкретная причина указана в message.
• У прокси должен быть публичный адрес. Для целевого URL действуют те же ограничения, что и без прокси: доступ к адресам внутренней сети запрещён.
• При доступе к сайтам через прокси соблюдайте условия использования целевого сайта и местное законодательство.

Чтобы сделать скриншот страницы, доступной только после входа, передайте данные сеанса своей учётной записи. Есть два способа: передать cookies, headers, local_storage, session_storage прямо в запросе или сохранить сеанс как «профиль входа» через расширение Glanceshot для браузера и указать в запросе только login_profile.

curl -X POST "https://glanceshot.com/v1/screenshot"   -H "X-Access-Key: $GLANCESHOT_KEY"   -H "Content-Type: application/json"   -d '{
    "url": "https://app.example.com/dashboard",
    "cookies": "sid=YOUR_SESSION; theme=dark",
    "local_storage": {"token": "YOUR_TOKEN"}
  }' -o screenshot.png

• Расширение может считывать данные авторизации, недоступные скриптам страницы (включая HttpOnly Cookie), а также localStorage и IndexedDB. Подходит для большинства сайтов. Установите и подключите расширение на странице «Профили входа» в консоли.
• Данные сеанса можно передавать только в теле POST-запроса (GET и подписанные URL отклоняются). Они не попадают в логи и историю запросов. Запросы с данными сеанса кэшируются отдельно с учётом этих данных; кэш не используется совместно с другими пользователями.
• Если данные сеанса переданы, но сайт перенаправляет на страницу входа, возвращается login_expired. Такой запрос не оплачивается: сеанс больше не действителен, и его нужно повторно синхронизировать через расширение.
• Если сеанс сайта привязан к устройству или IP и вход нельзя воспроизвести в облаке (например, в интернет-банке), используйте функцию расширения «Снимок текущей страницы», чтобы сделать скриншот в своём браузере и загрузить его.

Запросы с одинаковыми параметрами используют кеш (пропущенный параметр и явно заданное значение по умолчанию считаются одинаковыми; параметры аутентификации и кеширования не сравниваются). При попадании в кеш в бинарном режиме возвращается перенаправление 302 на адрес файла с заголовком Cache-Control; браузер автоматически переходит по адресу и кеширует файл. В режиме JSON возвращается cache_hit: true.

Запросы из кеша не оплачиваются.Одновременные запросы с одинаковыми параметрами запускают рендеринг только один раз.

• Оплачиваются только успешные запросы (2xx), не попавшие в кеш: скриншот — 1 единица квоты, PDF — 2.
• При тайм-ауте, сбое рендеринга, ошибке или блокировке доступа на целевом сайте, неверных параметрах или ошибке авторизации квота не расходуется.
• Квота обновляется каждый календарный месяц (UTC). В бесплатном тарифе доступно 100 запросов в месяц; после исчерпания квоты возвращается quota_exceeded.
• При превышении лимита запросов в секунду или одновременных запросов возвращается 429. Заголовок Retry-After содержит рекомендуемое время ожидания в секундах.
• Рендеринг — не более 30 секунд; загрузка данных одной страницы — не более 50 MB; размер итогового файла — не более 50 MB.

Подробные лимиты тарифов: Тарифы.

Все ошибки возвращаются в формате JSON:

{
  "error": {
    "code": "render_failed",
    "message": "target responded with an error status",
    "upstream_status": 404,
    "request_id": "req_01j…"
  }
}

Отправьте 1–100 адресов одним запросом. Метод сразу вернёт ID задания (HTTP 202), а скриншоты будут создаваться по очереди в фоне. Подходит для пакетной обработки без долгого ожидания ответа. Можно периодически запрашивать статус или указать webhook_url, чтобы получить уведомление по завершении. Аутентификация такая же, как у синхронных методов (только через заголовок или параметр access_key; подписанные URL не поддерживаются).

curl -X POST "https://glanceshot.com/v1/batch" \
  -H "X-Access-Key: $GLANCESHOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "screenshot",
    "urls": ["https://example.com", "https://example.org"],
    "options": { "full_page": true, "format": "webp" },
    "webhook_url": "https://your-app.com/hooks/glanceshot"
  }'

# Возвращает 202
{
  "id": "bat_01j…",
  "type": "screenshot",
  "status": "queued",
  "total": 2, "succeeded": 0, "failed": 0,
  "created_at": "2026-10-18T09:30:00Z", "completed_at": null,
  "webhook": { "url": "https://your-app.com/hooks/glanceshot", "status": "none", "attempts": 0 },
  "items": [
    { "index": 0, "url": "https://example.com", "status": "pending", "result": null, "error": null },
    { "index": 1, "url": "https://example.org", "status": "pending", "result": null, "error": null }
  ]
}

Проверка прогресса: статус задания status последовательно принимает значения queued (в очереди), running (обрабатывается), completed (обработка завершена, независимо от результата). Статус каждого адреса — pending, running, succeeded или failed. При успехе result содержит адрес файла, при ошибке error содержит код ошибки (такой же, как у синхронных методов).

curl "https://glanceshot.com/v1/batch/bat_01j…" -H "X-Access-Key: $GLANCESHOT_KEY"

{
  "id": "bat_01j…",
  "status": "completed",
  "total": 2, "succeeded": 1, "failed": 1,
  "completed_at": "2026-10-18T09:30:12Z",
  "items": [
    {
      "index": 0, "url": "https://example.com", "status": "succeeded", "duration_ms": 1830,
      "result": { "url": "https://glanceshot.com/i/3f/3f9c….webp", "mime": "image/webp", "width": 1280, "height": 2410, "cache_hit": false },
      "error": null
    },
    {
      "index": 1, "url": "https://example.org", "status": "failed", "duration_ms": 640,
      "result": null,
      "error": { "code": "render_failed", "message": "target responded with an error status" }
    }
  ]
}

• Оплата как у синхронных методов: за каждый успешно обработанный адрес списывается 1 единица квоты для скриншота или 2 для PDF. Результаты из кеша и ошибки квоту не расходуют.
• Если квота исчерпана при отправке задания, сразу возвращается quota_exceeded. Если она закончится во время обработки, оставшиеся адреса завершатся с ошибкой quota_exceeded.
• На аккаунт допускается не более 5 незавершённых пакетных заданий одновременно. При превышении возвращается too_many_batches.
• Срок хранения файлов результата определяется параметром options.cache_ttl (по умолчанию 1 день). Скачайте и сохраните их вовремя.
• В результатах запроса и уведомлениях webhook.url отображается только до пути, без строки запроса.

Если указан webhook_url, после завершения всего задания мы отправим на него запрос POST с телом JSON: { "event": "batch.completed", "batch": { … } }. Поле batch полностью совпадает с ответом метода проверки статуса. Заголовки:

• X-Glanceshot-Signature: t=1760779812,v1=5d3f…: t — время отправки (в секундах Unix), v1 — подпись
• X-Glanceshot-Event: batch.completed, X-Glanceshot-Delivery-Attempt: 1 (номер попытки доставки)

v1 = hex(HMAC-SHA256(secret, t + "." + Исходное тело запроса))
secret — секрет для подписи, связанный с API Key, использованным при создании задачи (доступен на странице API Key в консоли).

• Верните ответ 2xx в течение 10 секунд, иначе доставка считается неудачной. При сбое выполняется по одной повторной попытке через 10 секунд, 1 минуту и 5 минут (не более 4 попыток всего).
• В редких случаях уведомление об одной задаче может прийти повторно. Удаляйте дубликаты по batch.id.
• Для проверки подписи используйте полученные исходные байты. Убедитесь, что t отличается от текущего времени не более чем на несколько минут, чтобы предотвратить атаки повторного воспроизведения.
• Адрес обратного вызова должен быть общедоступным адресом http(s) и не может указывать на внутреннюю сеть.

import crypto from "node:crypto";

// rawBody должен содержать исходные полученные байты. Нельзя сначала выполнять JSON.parse, а затем повторную сериализацию
function verifyGlanceshotWebhook(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false; // Защита от повторного воспроизведения
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const got = Buffer.from(parts.v1 ?? "");
  return got.length === expected.length && crypto.timingSafeEqual(Buffer.from(expected), got);
}

// verifyGlanceshotWebhook(req.rawBody, req.headers["x-glanceshot-signature"], GLANCESHOT_SECRET)

Не требует авторизации. Возвращает состояние узла и пула браузеров: общее число, занятые и свободные.