S-SHOT logo
S-SHOT
Студия структурированных веб-данных
Справочник

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

Документация по API S-SHOT на каноническом хосте `www.s-shot.ru`. Публичная песочница выполняет только асинхронные запросы; синхронные и `download`-сценарии остаются справочными примерами.

Текущий режим: асинхронный
Нужен API-ключ?Зарегистрируйтесьиливойдитечтобы начать вызывать API.

Быстрый старт

Базовые значения для копирования

Начните с канонического базового URL `www.s-shot.ru`, заголовка авторизации и основных методов API.

Базовый URL
https://www.s-shot.ru
Заголовок Authorization
Authorization: Bearer $API_KEY
Синхронный метод
POST https://www.s-shot.ru/v1.0/extract
Асинхронный метод
POST https://www.s-shot.ru/v1.0/extract-async
Метод download (справка)
POST https://www.s-shot.ru/v1.0/download

Синхронный режим и `download` описаны ниже как reference-only контракты. Публичная песочница на `www.s-shot.ru` выполняет только асинхронные запросы и последующий опрос статуса.

Режим download для многошаговых сценариев

Используйте режим download, когда нужен захват файлов, извлечение с учетом сетевого поведения или многошаговый сценарий вместо обычного запроса с полем prompt.

1. Используйте метод download

Отправляйте тело запроса с полем workflow в метод download, а не в синхронный или асинхронный метод извлечения.

Метод download
POST https://www.s-shot.ru/v1.0/download
2. Добавьте трассировку запроса

Если в теле запроса есть объект workflow, добавляйте x-request-id, чтобы сервис мог связать запрос с сеансом download.

Обязательный заголовок
x-request-id: your-stable-request-id
3. Используйте code examples для download

На публичном `www` режим `download` не исполняется интерактивно. Используйте эту секцию как source-of-truth для payload shape, обязательного x-request-id и код-примеров.

Песочница

На публичном `www.s-shot.ru` песочница выполняет только POST /v1.0/extract-async и GET /v1.0/runs/{run_id}. Синхронный метод и `download` ниже остаются documentation-only примерами для интеграции.

Публичная песочница `extract-async`
Interactive mode: async only

Запуски идут через прокси на стороне сервера, чтобы избежать CORS и не держать long-running HTTP-запросы на `www.s-shot.ru`. Ваш API-ключ никогда не показывается на этой странице.

Скриншот
Добавляет поле screenshot_url, когда снимок доступен.
Расширенные параметры
Необязательные поля schema_id, schema и language.
JSON запроса
{
  "url": "https://www.example.com/product/1234",
  "prompt": "technical specifications",
  "options": {
    "timeout_ms": 30000,
    "wait_until": "load",
    "wait_for_selector": "#price"
  }
}
Сгенерированный код
curl -X POST https://www.s-shot.ru/v1.0/extract-async \
  -H 'Authorization: Bearer $API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000' \
  -d @- <<'JSON'
{
  "url": "https://www.example.com/product/1234",
  "prompt": "technical specifications",
  "options": {
    "timeout_ms": 30000,
    "wait_until": "load",
    "wait_for_selector": "#price"
  }
}
JSON
Ответ
Запустите запрос, чтобы увидеть ответ здесь.

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

Передавайте ключ как bearer token в каждом запросе.

Заголовок
Authorization: Bearer $API_KEY

Методы API

Переключайтесь между синхронным и асинхронным режимами.

Асинхронный метод

POST/v1.0/extract-async

Запускает асинхронное извлечение и возвращает run_id, URL для WebSocket-подключения и токен.

GET/v1.0/runs/{run_id}

Опрос статуса и результата асинхронного запуска.

WS/ws/{run_id}?token=…

Потоковая передача статуса, прогресса и результата; токен привязан к конкретному запуску и действует недолго.

Необязательный заголовок: Idempotency-Key для защиты от повторной отправки запроса в течение 24 часов.

Тело запроса

{
  "url": "https://example.com/page",              // required
  "prompt": "Extract product name & price",    // required, max 2048 chars
  "options": {
    "timeout_ms": 30000,                       // 1–120000
    "screenshot": false                        // optional
  }
}

Токены для WebSocket-подключений действуют недолго, обычно около 5 минут.

Ответы

{
  "run_id": "run_234b534e-23e2-448c-9043-bc816eaa391a",
  "status_url": "/v1.0/runs/run_234b534e-23e2-448c-9043-bc816eaa391a",
  "websocket": "/ws/run_234b534e-23e2-448c-9043-bc816eaa391a?token=…",
  "websocket_token": "…",
  "websocket_token_expires_at": 1733421457
}

WebSocket

Подключайтесь к адресу websocket, который приходит из /v1.0/extract-async. Сервер сразу отправляет снимок текущего статуса.

// Message types
{ "type": "status", "run_id": "...", "status": "queued|running|success|failed", "step": "download|semantic|parse" }
{ "type": "started", "run_id": "...", "request_id": "..." }
{ "type": "progress", "run_id": "...", "step": "download|semantic|parse" }
{ "type": "result", "run_id": "...", "json": { ... }, "screenshot_url": "..." }
{ "type": "error", "run_id": "...", "step": "download", "message": "...", "retryable": false }
{ "type": "done", "run_id": "...", "status": "success|failed" }
{ "type": "ping", "ts": 1733421457 }

Примеры кода

curl -X POST https://www.s-shot.ru/v1.0/extract-async \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer $API_KEY' \
  -H 'Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000' \
  -d '{
    "url": "https://www.example.com/product/1234",
    "prompt": "technical specifications",
    "options": { "screenshot": true, "timeout_ms": 30000 }
  }'

Лимиты и оплата

  • Лимит параллельных запусков по тарифам: Хобби 1, Базовый 5, Про 20, Индивидуальный по договору.
  • Когда исчерпан лимит параллельных запусков, сервис возвращает 429, включая Retry-After: 1.
  • Тарифицируемые запросы: POST /v1.0/extract и POST /v1.0/extract-async; тарификация происходит в момент принятия запроса.
  • Опрос асинхронного статуса и сообщения по WebSocket не тарифицируются.
  • Таймаут по умолчанию 30 с, максимум 120 с, длина поля prompt до 2048 символов.