v1

latestOpenAPI 3.1.02026-07-171921144.8 KB

realtime

Create a real-time VLM alert rule

Start monitoring a live RTSP stream for a single alert_type. On success returns the rule's id, which you pass as alert_rule_id to GET / DELETE /api/v1/realtime/{alert_rule_id}.

Stream sharing

Provide sensor_id to share one underlying RTVI stream across multiple rules:

If RTVI already has a stream registered with that id, it is reused — no extra connection to the camera.
Otherwise a new stream is opened.
The stream is only torn down when the last rule using it is deleted.

How a create is validated

The rule is persisted (if persistence is enabled).
The RTVI stream is opened (or reused).
The service waits briefly for caption generation to start and, for new streams, polls RTVI until the stream is visible.
If the RTSP source cannot be opened, you get a 502 with rtvi_stream_not_readable — no silent late failure.

When you might get blocked

While POST /api/v1/realtime/replay is running, this endpoint returns 503 replay_in_progress. Retry once the replay finishes.

post/api/v1/realtime

Request body

live_stream_urlstring required

RTSP URL of the live stream to monitor

sensor_idstring nullable

Sensor ID from VIOS, used as the stream identifier in RTVI VLM. Optional: when omitted, the field is forwarded to RTVI as null and RTVI assigns its own stream identifier.

sensor_namestring nullable

Optional human-readable camera/sensor label. Forwarded verbatim to RTVI's /streams/add sensor_name; downstream sinks use it to correlate alerts/captions back to a camera. Always-on callers populate this from the VST event's camera_name automatically.

descriptionstring nullable

Description of the live stream

usernamestring nullable

RTSP authentication username

passwordstring nullable

RTSP authentication password

place_namestring nullable

Name of the monitored location

place_typestring nullable

Type of the monitored location

place_latstring nullable

Latitude of the monitored location

place_lonstring nullable

Longitude of the monitored location

place_altstring nullable

Altitude of the monitored location

place_coordinate_xstring nullable

X coordinate within the facility map

place_coordinate_ystring nullable

Y coordinate within the facility map

alert_typestring required

Alert type label for this rule (e.g. 'collision')

promptstring required

User prompt describing what to detect / analyse

system_promptstring

Optional system prompt for the VLM

modelstring

VLM model name. If empty, the service falls back to 'rtvi_vlm.default_model' from the Alert Bridge config. At least one of the two must be non-empty; otherwise the request is rejected with 422.

chunk_durationinteger

Duration (seconds) of each video chunk sent to VLM

chunk_overlap_durationinteger

Overlap (seconds) between consecutive chunks

num_frames_per_second_or_fixed_frames_chunkinteger

Same as RTVI VLM generate_captions_alerts: FPS when use_fps_for_chunking is true, else fixed frames per chunk

use_fps_for_chunkingboolean

RTVI VLM: if true, num_frames_per_second_or_fixed_frames_chunk is FPS; if false, fixed frame count per chunk

vlm_input_widthinteger

RTVI: VLM input image width

vlm_input_heightinteger

RTVI: VLM input image height

enable_reasoningboolean

RTVI: enable VLM reasoning

api_typestring nullable

RTVI: API type hint forwarded verbatim (e.g. 'internal')

response_formatobject nullable

RTVI: response format object (e.g. {"type": "text"})

stream_optionsobject nullable

RTVI: streaming options (e.g. {"include_usage": true})

max_tokensinteger nullable

RTVI: maximum tokens to generate

temperaturenumber nullable

RTVI: sampling temperature

top_pnumber nullable

RTVI: nucleus sampling probability

top_kinteger nullable

RTVI: top-k sampling

ignore_eosboolean nullable

RTVI: ignore end-of-sequence token

seedinteger nullable

RTVI: random seed for reproducibility

media_infoobject nullable

RTVI: media window descriptor (e.g. {"type": "offset", "start_offset": 0, "end_offset": 4000000000})

enable_audioboolean nullable

RTVI: include audio in VLM analysis

mm_processor_kwargsobject nullable

RTVI: additional multimodal processor kwargs

Example request

{
  "alert_type": "collision",
  "chunk_duration": 30,
  "chunk_overlap_duration": 5,
  "enable_reasoning": true,
  "live_stream_url": "rtsp://localhost:8554/media/video1",
  "model": "nvidia/cosmos3-nano-reasoner",
  "num_frames_per_second_or_fixed_frames_chunk": 10,
  "place_lat": "37.3706",
  "place_lon": "-121.9672",
  "place_name": "Dock Entrance-East",
  "place_type": "warehouse-bay",
  "prompt": "Detect vehicle collisions or near-miss events in this traffic camera feed.",
  "sensor_id": "cc06804c-7f11-4865-bb00-6b2db072086f",
  "sensor_name": "Camera_123",
  "system_prompt": "You are a traffic safety monitoring assistant.",
  "use_fps_for_chunking": true,
  "vlm_input_height": 256,
  "vlm_input_width": 256
}

Response

Alert rule created successfully.

statusstring

idstring required

Unique alert rule ID for subsequent management

created_atstring required

ISO-8601 creation timestamp

messagestring

Example response

{
  "created_at": "2025-06-01T12:00:00Z",
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "message": "Realtime alert rule created",
  "status": "success"
}