API Reference — Snapshot Detection
Endpoint REST API untuk membuat, mengelola, dan memantau pipeline Snapshot Detection (varian NFV4D-*), serta struktur event JSON.
← Kembali ke Snapshot Detection
Pengenalan, varian, persyaratan, konfigurasi, dan best practice Snapshot Detection.
Konfigurasi Snapshot Detection
Referensi lengkap parameter body pipeline per varian.
Semua endpoint pada halaman ini menggunakan basis URL dari variabel VISIONAIRE_API_URL yang dikonfigurasi pada instalasi Visionaire (default: http://localhost:4004). Tidak ada autentikasi tambahan yang diperlukan selain akses jaringan ke host tersebut. Snapshot Detection tidak memanggil FREMIS-N — endpoint ini seluruhnya adalah Visionaire API sendiri; layanan AI eksternal tempat inferensi berjalan tidak diekspos lewat Visionaire API (lihat Persyaratan — Dependensi).
Manajemen Pipeline
Setiap pipeline diidentifikasi oleh kombinasi node_num, stream_id, dan analytic_id. {analytic_id} adalah salah satu dari 15 varian NFV4D-* (lihat Varian & Cara Kerja) — semua varian memakai path endpoint yang sama, perbedaannya hanya pada isi body config saat pembuatan.
Buat Pipeline
POST /pipeline/{node_num}/{stream_id}/{analytic_id}
curl -X POST http://localhost:4004/pipeline/0/stream_factory_01/NFV4D-FISO \
-H "Content-Type: application/json" \
-d '{
"config": {
"address": "http://ai-service:4006",
"dump_interval": 5,
"dump_confidence": 0.30,
"areas": [
{
"name": "Zona Produksi",
"roi_type": "whitelist",
"points": [
{"x": 0.1, "y": 0.1},
{"x": 0.9, "y": 0.1},
{"x": 0.9, "y": 0.9},
{"x": 0.1, "y": 0.9}
]
}
]
}
}'curl -X POST http://localhost:4004/pipeline/0/stream_warehouse_03/NFV4D-PSMO \
-H "Content-Type: application/json" \
-d '{
"config": {
"address": "http://ai-service:4006",
"dump_interval": 5,
"dump_confidence": 0.30
}
}'curl -X POST http://localhost:4004/pipeline/0/stream_lobby_07/NFV4D-OVOD \
-H "Content-Type: application/json" \
-d '{
"config": {
"address": "http://ai-service:4006",
"dump_interval": 5,
"classes": ["person", "backpack", "luggage"],
"confidence": 0.5,
"additional_params": {
"box_th": 0.3,
"text_th": 0.25
}
}
}'curl -X POST http://localhost:4004/pipeline/0/stream_publicarea_02/NFV4D-VMFG \
-H "Content-Type: application/json" \
-d '{
"config": {
"address": "http://ai-service:4008",
"dump_interval": 10,
"images_num": 4,
"interval_capture": 0.5,
"is_dump_collage": true
}
}'curl -X POST http://localhost:4004/pipeline/0/stream_terminal_01/NFV4D-VLM \
-H "Content-Type: application/json" \
-d '{
"config": {
"address": "http://ai-service:4008",
"dump_interval": 15,
"persona": "public_safety"
}
}'Response Sukses (200)
{
"code": 200,
"message": "pipeline successfully created",
"node_num": 0,
"stream_id": "stream_factory_01",
"analytic_id": "NFV4D-FISO"
}Bila pipeline dengan analytic_id yang sama sudah berjalan pada stream tersebut, request ditolak dengan status 400 dan pesan "analytic_id=<id> is already exists in stream=<stream_id> !".
Perbarui Konfigurasi Pipeline
PUT /pipeline/{node_num}/{stream_id}/{analytic_id}
Memperbarui parameter pipeline yang sedang berjalan tanpa restart. Body sama seperti POST.
curl -X PUT http://localhost:4004/pipeline/0/stream_factory_01/NFV4D-FISO \
-H "Content-Type: application/json" \
-d '{
"config": {
"dump_confidence": 0.45,
"dump_interval": 8
}
}'Response sukses (200): {"code": 200, "message": "pipeline successfully updated", "node_num": 0, "stream_id": "stream_factory_01", "analytic_id": "NFV4D-FISO"}.
Baca Konfigurasi Pipeline
GET /pipeline/{node_num}/{stream_id}/{analytic_id}
curl http://localhost:4004/pipeline/0/stream_factory_01/NFV4D-FISO{
"code": 200,
"node_num": 0,
"stream_id": "stream_factory_01",
"analytic_id": "NFV4D-FISO",
"config": {
"address": "http://ai-service:4006",
"dump_interval": 5,
"dump_confidence": 0.3
},
"message": "configuration has been successfully retrieved from the db"
}Untuk seluruh varian Snapshot Detection, endpoint ini mengembalikan konfigurasi yang tersimpan di database (persis seperti yang terakhir dikirim lewat POST/PUT), bukan konfigurasi runtime yang sudah digabung dengan default terverbose — mekanisme "verbose config registry" seperti pada Face Recognition (NFV4-FR, dst.) tidak berlaku untuk varian NFV4D-*.
Hapus Pipeline
DELETE /pipeline/{node_num}/{stream_id}/{analytic_id}
curl -X DELETE http://localhost:4004/pipeline/0/stream_factory_01/NFV4D-FISOResponse sukses (200): {"code": 200, "message": "pipeline successfully deleted", "node_num": 0, "stream_id": "stream_factory_01", "analytic_id": "NFV4D-FISO"}. Pipeline yang sudah dihapus tidak dapat dipulihkan; buat ulang jika diperlukan.
Cek Default Konfigurasi Varian
GET /config/pipeline/{analytic_id}/ (atau GET /v2/config/pipeline/{analytic_id}/)
Mengembalikan daftar parameter yang didaftarkan varian tersebut sebagai "verbose config" — dipakai antara lain untuk membangun form konfigurasi di UI.
Dari 15 varian NFV4D-*, hanya NFV4D-RIOT dan NFV4D-VLM yang mendaftarkan verbose config (lihat Konfigurasi). Memanggil endpoint ini untuk 13 varian lainnya (NFV4D-OVOD, NFV4D-OVIC, NFV4D-WLM, NFV4D-FLOD, NFV4D-PSMO, NFV4D-PPHO, NFV4D-FISO, NFV4D-PPFA, NFV4D-VMFG, NFV4D-VMVD, NFV4D-VMBG, NFV4D-ARVM, NFV4D-RCMA) akan mengembalikan daftar configs kosong — gunakan tabel parameter di halaman Konfigurasi sebagai referensi untuk varian-varian tersebut.
Tidak ada endpoint preset (GET /config/preset/{analytic_id}/ selalu kosong untuk NFV4D-*) — Snapshot Detection tidak mendaftarkan preset apa pun.
Event Streaming (WebSocket)
WS /event_channel/{node_num}/{stream_id}/{analytic_id}
Visionaire mengirim setiap event hasil dispatch melalui WebSocket. Setelah koneksi terbuka, server langsung mendorong (push) setiap event ke client tanpa handshake atau pesan subscribe tambahan.
Parameter Path
| Parameter | Tipe | Deskripsi |
|---|---|---|
node_num | integer | Nomor node tempat pipeline berjalan (0 = master). |
stream_id | string | ID Stream yang dipantau. |
analytic_id | string | ID varian Snapshot Detection (mis. NFV4D-FISO). |
Contoh Koneksi
const ws = new WebSocket(
'ws://localhost:4004/event_channel/0/stream_factory_01/NFV4D-FISO'
);
ws.onmessage = (msg) => {
const event = JSON.parse(msg.data);
console.log(event.primary_text, event.pipeline_data);
};
ws.onerror = (err) => console.error('WebSocket error', err);
ws.onclose = () => console.log('Disconnected');import asyncio
import json
import websockets
async def listen():
url = "ws://localhost:4004/event_channel/0/stream_factory_01/NFV4D-FISO"
async with websockets.connect(url) as ws:
async for msg in ws:
event = json.loads(msg)
print(event["primary_text"], event["pipeline_data"])
asyncio.run(listen())Endpoint Channel Lainnya
| Endpoint | Cakupan |
|---|---|
WS /event_channel/ | Semua event dari seluruh node |
WS /event_channel/{node_num}/ | Semua event dari satu node |
WS /event_channel/{node_num}/{stream_id} | Semua event dari satu stream (semua analitik) |
Live View (MJPEG)
GET /mjpeg/{node_num}/{stream_id}/{analytic_id} menghasilkan MJPEG stream dengan overlay pipeline (ROI, bounding box) — berguna untuk memverifikasi konfigurasi areas secara visual. Tanpa {analytic_id} (GET /mjpeg/{node_num}/{stream_id}), endpoint ini menampilkan stream mentah tanpa overlay analitik apa pun.
Query Parameter
| Parameter | Tipe | Default | Deskripsi |
|---|---|---|---|
fps | integer | 0 | Frame per detik output MJPEG. |
height | integer | 320 | Tinggi output dalam piksel. |
jq | integer | 60 | Kualitas JPEG (0–100). |
curl "http://localhost:4004/mjpeg/0/stream_factory_01/NFV4D-FISO?fps=10&height=480&jq=70"GET /visual/{node_num}/{stream_id}/{analytic_id} bukan endpoint MJPEG — ia mengembalikan halaman HTML viewer, bukan gambar/stream langsung. Untuk mengambil MJPEG secara terprogram, gunakan /mjpeg/... di atas. Path /pipeline/{node_num}/{stream_id}/{analytic_id}/mjpeg dan /pipeline/.../snapshot yang muncul di dokumentasi versi lama tidak ada — endpoint MJPEG selalu berada di bawah prefix /mjpeg/..., terpisah dari /pipeline/....
Struktur Event
Semua event Snapshot Detection memakai envelope yang sama dengan modul analitik Visionaire lainnya. Bagian spesifik per varian ada di pipeline_data.
{
"timestamp": 1714800000,
"node_num": 1,
"stream_id": "stream_factory_01",
"stream_name": "Gudang Produksi",
"stream_address": "rtsp://10.7.2.60:554/stream",
"stream_longitude": 106.823649,
"stream_latitude": -6.261376,
"analytic_id": "NFV4D-FISO",
"primary_text": "fire",
"secondary_text": "0.812000",
"pipeline_data": {
"event_id": "1714800000-1a2b3c4d",
"label": "fire",
"confidence": 0.812
},
"image_jpeg": "<base64 JPEG>"
}Field Envelope
| Field | Tipe | Deskripsi |
|---|---|---|
timestamp | int | Waktu event dalam epoch detik (UTC). |
node_num | int | Nomor node tempat pipeline berjalan. |
stream_id | string | Identifier stream sumber. |
stream_name | string | Nama stream. |
stream_address | string | URL sumber video stream. |
stream_longitude, stream_latitude | float | Posisi kamera. |
analytic_id | string | Varian pipeline yang memancarkan event (NFV4D-*). |
primary_text | string | Teks utama event — bervariasi per varian (label objek, nama event VLM, atau angka level WLM). |
secondary_text | string | Teks pelengkap — bervariasi per varian (confidence, atau kosong). |
pipeline_data | object | Payload spesifik per varian — lihat tabel di bawah. |
image_jpeg | string (base64) | Snapshot Frame (atau crop objek/collage) yang menjadi bukti deteksi. |
Tidak ada event_id di level atas envelope — event_id (format <timestamp>-<hash8>) hanya ada di dalam pipeline_data.
Field pipeline_data per Kelompok Varian
| Field | Tipe | Tersedia Pada |
|---|---|---|
event_id | string | Semua varian |
label | string | Deteksi ROI: OVOD (bila context dikonfigurasi), PSMO, PPHO, FISO, PPFA |
confidence | float | Deteksi ROI: PSMO, PPHO, FISO, PPFA |
dump | boolean | OVOD tanpa context — penanda dump (selalu true saat event diterbitkan) |
labels | object | OVIC — mapping label → boolean apa adanya dari respons layanan eksternal |
<label> (dinamis) | float | FLOD — nilai confidence mentah untuk label yang cocok (mis. "waterlogged": 87.3) |
attributes.classification.label / .confidence | string / float | FLOD |
level | number | WLM |
event | boolean | Semua varian VLM (VMFG, VMVD, VMBG, RIOT, VLM mode LEGACY_RAW/FREE_COT, ARVM, RCMA) — true bila kondisi target terpenuhi |
answer | string | Semua varian VLM — jawaban dari VLM (mentah pada LEGACY_RAW, "yes"/"no" pada FREE_COT, deskripsi hasil parsing pada PRESET_PERSONA) |
persona | string | NFV4D-VLM — kosong pada LEGACY_RAW, "free" pada FREE_COT, atau nama preset pada PRESET_PERSONA |
severity | string | NFV4D-VLM mode PRESET_PERSONA — salah satu vocabulary persona, atau "parse_failed"/"out_of_vocab" |
votes / min_votes | int | NFV4D-VLM mode FREE_COT |
cot_answers | array string | NFV4D-VLM mode FREE_COT dan PRESET_PERSONA — jawaban mentah tiap prompt CoT |
detections | array | Opsional pada varian VLM bila jawaban mengandung koordinat lokasi terparsir |
Contoh Event per Varian
{
"analytic_id": "NFV4D-FISO",
"stream_id": "stream_factory_01",
"node_num": 1,
"timestamp": 1714800000,
"primary_text": "fire",
"secondary_text": "0.812000",
"pipeline_data": { "event_id": "1714800000-1a2b3c4d", "label": "fire", "confidence": 0.812 }
}{
"analytic_id": "NFV4D-PSMO",
"stream_id": "stream_warehouse_03",
"node_num": 1,
"timestamp": 1714800120,
"primary_text": "person smoking",
"secondary_text": "0.421000",
"pipeline_data": { "event_id": "1714800120-9f8e7d6c", "label": "person smoking", "confidence": 0.421 }
}{
"analytic_id": "NFV4D-OVOD",
"stream_id": "stream_lobby_07",
"node_num": 2,
"timestamp": 1714800300,
"primary_text": "Main Lobby: person",
"secondary_text": "0.762000",
"pipeline_data": { "event_id": "1714800300-2b3c4d5e", "dump": true }
}{
"analytic_id": "NFV4D-WLM",
"stream_id": "stream_river_05",
"node_num": 1,
"timestamp": 1714800900,
"primary_text": "900",
"secondary_text": "",
"pipeline_data": { "event_id": "1714800900-4d5e6f70", "level": 900 }
}{
"analytic_id": "NFV4D-FLOD",
"stream_id": "stream_road_02",
"node_num": 1,
"timestamp": 1714801200,
"primary_text": "waterlogged",
"secondary_text": "87.300 %",
"pipeline_data": {
"event_id": "1714801200-5e6f7081",
"waterlogged": 87.3,
"attributes": { "classification": { "label": "waterlogged", "confidence": 87.3 } }
}
}{
"analytic_id": "NFV4D-RIOT",
"stream_id": "stream_publicarea_02",
"node_num": 1,
"timestamp": 1714800600,
"primary_text": "Riot is Detected",
"secondary_text": "",
"pipeline_data": { "event_id": "1714800600-6f708192", "event": true, "answer": "yes" }
}{
"analytic_id": "NFV4D-VLM",
"stream_id": "stream_terminal_01",
"node_num": 1,
"timestamp": 1714801500,
"primary_text": "public safety event: suspicious",
"secondary_text": "Two people arguing near the ticket counter, no physical contact observed.",
"pipeline_data": {
"event_id": "1714801500-708192a3",
"event": true,
"answer": "Two people arguing near the ticket counter, no physical contact observed.",
"persona": "public_safety",
"severity": "suspicious",
"cot_answers": [
"Two people are standing close, gesturing animatedly.",
"Two people visible, body language agitated.",
"No weapons or broken objects visible; raised voices only."
]
}
}