К содержанию
ShotlyДокументация API

Скриншоты

Асинхронное создание скриншота

Создайте задачу, сохраните taskId и скачайте результат после завершения обработки.

Когда использовать асинхронный API

Асинхронный API доступен на FREE и PAID. Он подходит для фоновых задач и пакетной обработки: запрос сразу возвращает taskId, а обработка продолжается независимо от соединения с клиентом.

Создайте задачу

curl
curl --fail-with-body \
  -X POST "https://api.shotly.cloud/v1/screenshots" \
  -H "X-API-Key: $SHOTLY_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "url": "https://example.com",
    "browser": "chromium",
    "format": "png",
    "fullPage": true
  }'

POST /v1/screenshots принимает те же параметры скриншота, что и синхронный API, включая выбор страницы, видимой области или элемента по selector. API-ключ передавайте в X-API-Key; правила хранения ключа описаны в разделе «Аутентификация».

Успешный ответ имеет статус 202 Accepted:

json
{
  "taskId": "9f0c6a7e-7d7f-4a62-9d70-7c7ddf4c8e52"
}

Проверьте статус

curl
curl --fail-with-body \
  -H "X-API-Key: $SHOTLY_API_KEY" \
  "https://api.shotly.cloud/v1/screenshots/9f0c6a7e-7d7f-4a62-9d70-7c7ddf4c8e52"
json
{
  "taskId": "9f0c6a7e-7d7f-4a62-9d70-7c7ddf4c8e52",
  "status": "IN_PROGRESS",
  "resultUrl": null,
  "errorMessage": null,
  "payloadSize": null,
  "createdAt": "2026-07-11T09:00:00Z",
  "updatedAt": "2026-07-11T09:00:02Z"
}

PENDING и IN_PROGRESS — незавершённые статусы. DONE и ERROR завершают задачу. Полная модель переходов описана на странице «Статусы задач».

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

Ожидание в запросе статуса

По умолчанию timeoutSeconds=0, поэтому API сразу возвращает текущее состояние. На PAID можно передать значение от 1 до 60:

curl
curl --fail-with-body \
  -H "X-API-Key: $SHOTLY_API_KEY" \
  "https://api.shotly.cloud/v1/screenshots/<taskId>?timeoutSeconds=30"

API ждёт, пока задача перейдёт в DONE или ERROR, но не дольше заданного времени. Если задача не завершилась, API всё равно возвращает HTTP 200 и JSON с текущим статусом.

Это не синхронный POST /take: запрос статуса не возвращает изображение и не использует ответ 202 для продолжения.

Скачайте результат

resultUrl появляется только при DONE. Поле payloadSize содержит размер изображения, если он известен.

shell
curl --fail --location --output screenshot.png "<resultUrl>"

Ссылка временная. Если она истекла, снова запросите статус и используйте новый resultUrl.

Если задача завершилась ошибкой

ERROR завершает задачу. Поле errorMessage может содержать описание ошибки, а resultUrl будет равно null. Остановите опрос; создание новой задачи снова расходует квоту.

Доступ к задаче

Прочитать задачу можно только с API-ключом, который её создал. Для отсутствующей или чужой задачи API возвращает 404. Не публикуйте временную ссылку на результат без необходимости.