Vision API — видеоаналитика и CV-события

Базовый URL

https://vision.a5x.pro/api

Authorization: Bearer YOUR_API_KEY. Ключ выдаётся в личном кабинете после подключения модуля A5X Vision.

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

curl -X POST "https://vision.a5x.pro/api/v1/streams" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Склад — ворота A",
    "rtsp_url": "rtsp://user:pass@192.168.1.10:554/stream1",
    "scenarios": ["ppe", "safety"],
    "webhook_url": "https://example.com/webhooks/vision"
  }'

Сценарии CV

Поле	Тип	Описание
`traffic`	scenario	Подсчёт уникального трафика, тепловые карты, очереди.
`ppe`	scenario	Контроль СИЗ: каски, жилеты, маски, перчатки.
`safety`	scenario	Огонь, задымление, падение, запретные зоны.
`lpr`	scenario	Распознавание госномеров и контейнеров.
`barcode`	scenario	Штрихкоды и маркировки на складе.

Cloud / Edge

Edge-агент на объекте: буферизация при потере связи, отправка метаданных и снимков в A5X Cloud.
В облаке — дашборды, агрегаты трафика, SLA-алерты и REST API для интеграций.

Регистрация видеопотока

POSThttps://vision.a5x.pro/api/v1/streams

Подключение RTSP-камеры и выбор сценариев аналитики.

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

Поле	Тип	Описание
`name`*	string	Человекочитаемое имя камеры.
`rtsp_url`*	string	URL RTSP-потока (H.264).
`scenarios`*	string[]	Список сценариев: traffic, ppe, safety, lpr, barcode.
`site_id`	string	ID объекта / филиала в вашей системе.
`geo`	object	Опциональные координаты и этаж для карт.
`webhook_url`	string (uri)	URL (http/https, до 4096 символов) для POST-уведомления о новых событиях детекции по этому потоку.

201 Created

{
  "id": "STR_01",
  "name": "Склад — ворота A",
  "status": "connecting",
  "scenarios": ["ppe", "safety"],
  "created_at": "2026-06-27T12:00:00Z"
}

Коды ответов

HTTP	error.code	Ситуация
201	—	Поток принят, идёт подключение.
400	`invalid_rtsp`	Неверный URL или неподдерживаемый кодек.
401	`invalid_api_key`	Ключ недействителен.
402	`stream_limit_exceeded`	Превышен лимит камер по тарифу.

Статус потока

GEThttps://vision.a5x.pro/api/v1/streams/{stream_id}

Текущее состояние подключения, активные сценарии и последняя активность.

200 OK

{
  "id": "STR_01",
  "status": "online",
  "fps": 25,
  "latency_ms": 87,
  "last_event_at": "2026-06-27T17:42:13Z"
}

События детекции

GEThttps://vision.a5x.pro/api/v1/events

Выборка событий CV за период: нарушения СИЗ, срабатывания зон, распознанные номера.

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

Поле	Тип	Описание
`stream_id`	string	Фильтр по камере.
`scenario`	string	traffic \| ppe \| safety \| lpr \| barcode.
`from`	datetime	Начало периода (ISO 8601, UTC).
`to`	datetime	Конец периода (ISO 8601, UTC).
`limit`	integer	До 100. По умолчанию 50.
`cursor`	string	Пагинация: cursor из предыдущего ответа.

200 OK

{
  "items": [
    {
      "id": "EVT_8842",
      "stream_id": "STR_01",
      "scenario": "ppe",
      "type": "safety_vest_missing",
      "confidence": 0.94,
      "occurred_at": "2026-06-27T17:42:13Z",
      "snapshot_url": "https://vision.a5x.pro/media/snapshots/EVT_8842.jpg",
      "metadata": { "zone": "Zone_A" }
    }
  ],
  "next_cursor": "eyJpZCI6Ijg4NDIifQ"
}

Webhooks

Чтобы не опрашивать список событий, укажите webhook_url при регистрации потока. Когда появится новое событие детекции, на этот URL придёт POST.

Ответьте HTTP 2xx в течение ~15 секунд. Иначе уведомление будет отправлено повторно.
Повторы при ошибке или таймауте: через 15 с → 1 мин → 5 мин → 15 мин → 1 ч → 4 ч. После исчерпания попыток доставка прекращается.
Редиректы не поддерживаются. URL — http или https.
Проверяйте подпись X-Webhook-Signature: секрет — hex(SHA-256 вашего API-ключа), подпись — HMAC-SHA256 от сырого тела запроса.

Уведомления

Событие	Поля	Описание
`detection.created`	`event`, `event_id`, `stream_id`	Новое событие CV по потоку (СИЗ, зоны, номера и т.д.). `event_id` — тот же, что в GET `/v1/events`.

POST /hooks/vision HTTP/1.1
Host: example.com
Content-Type: application/json
User-Agent: a5x-webhook
X-Webhook-Signature-Alg: hmac-sha256
X-Webhook-Signature: sha256=<hex>

{"event":"detection.created","event_id":"EVT_8842","stream_id":"STR_01"}

Агрегаты трафика (Retail)

GEThttps://vision.a5x.pro/api/v1/analytics/traffic

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

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

Поле	Тип	Описание
`stream_id`*	string	Камера входной группы.
`granularity`	string	hour \| day. По умолчанию hour.
`from`*	date	Начало периода.
`to`*	date	Конец периода.

200 OK

{
  "stream_id": "STR_02",
  "granularity": "hour",
  "series": [
    { "bucket": "2026-06-27T17:00:00Z", "unique_visitors": 142, "avg_queue_sec": 38 }
  ]
}