---
title: "Create a real-time VLM alert rule"
method: POST
path: "/api/v1/realtime"
tags: ["realtime"]
---

# Create a real-time VLM alert rule

`POST /api/v1/realtime`

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
1. The rule is persisted (if persistence is enabled).
2. The RTVI stream is opened (or reused).
3. The service waits briefly for caption generation to start and, for new streams, polls RTVI until the stream is visible.
4. 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.

## Request body

- RealtimeAlertRequest — Request body for POST /api/v1/realtime.
  - `live_stream_url` string, required — RTSP URL of the live stream to monitor
  - `sensor_id` string, 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_name` string, 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.
  - `description` string, nullable — Description of the live stream
  - `username` string, nullable — RTSP authentication username
  - `password` string, nullable — RTSP authentication password
  - `place_name` string, nullable — Name of the monitored location
  - `place_type` string, nullable — Type of the monitored location
  - `place_lat` string, nullable — Latitude of the monitored location
  - `place_lon` string, nullable — Longitude of the monitored location
  - `place_alt` string, nullable — Altitude of the monitored location
  - `place_coordinate_x` string, nullable — X coordinate within the facility map
  - `place_coordinate_y` string, nullable — Y coordinate within the facility map
  - `alert_type` string, required — Alert type label for this rule (e.g. 'collision')
  - `prompt` string, required — User prompt describing what to detect / analyse
  - `system_prompt` string — Optional system prompt for the VLM
  - `model` string — 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_duration` integer — Duration (seconds) of each video chunk sent to VLM
  - `chunk_overlap_duration` integer — Overlap (seconds) between consecutive chunks
  - `num_frames_per_second_or_fixed_frames_chunk` integer — Same as RTVI VLM generate_captions_alerts: FPS when use_fps_for_chunking is true, else fixed frames per chunk
  - `use_fps_for_chunking` boolean — RTVI VLM: if true, num_frames_per_second_or_fixed_frames_chunk is FPS; if false, fixed frame count per chunk
  - `vlm_input_width` integer — RTVI: VLM input image width
  - `vlm_input_height` integer — RTVI: VLM input image height
  - `enable_reasoning` boolean — RTVI: enable VLM reasoning
  - `api_type` string, nullable — RTVI: API type hint forwarded verbatim (e.g. 'internal')
  - `response_format` object, nullable — RTVI: response format object (e.g. {"type": "text"})
  - `stream_options` object, nullable — RTVI: streaming options (e.g. {"include_usage": true})
  - `max_tokens` integer, nullable — RTVI: maximum tokens to generate
  - `temperature` number, nullable — RTVI: sampling temperature
  - `top_p` number, nullable — RTVI: nucleus sampling probability
  - `top_k` integer, nullable — RTVI: top-k sampling
  - `ignore_eos` boolean, nullable — RTVI: ignore end-of-sequence token
  - `seed` integer, nullable — RTVI: random seed for reproducibility
  - `media_info` object, nullable — RTVI: media window descriptor (e.g. {"type": "offset", "start_offset": 0, "end_offset": 4000000000})
  - `enable_audio` boolean, nullable — RTVI: include audio in VLM analysis
  - `mm_processor_kwargs` object, nullable — RTVI: additional multimodal processor kwargs

## Response `201`

Alert rule created successfully.

- RealtimeAlertResponse — Response returned when an alert rule is created.
  - `status` string
  - `id` string, required — Unique alert rule ID for subsequent management
  - `created_at` string, required — ISO-8601 creation timestamp
  - `message` string

## Other responses

- `422` — Request rejected before reaching RTVI. Common causes: - Invalid payload (missing field, bad RTSP URL, etc.) - No VLM model resolved — neither `model` in the request nor `rtvi_vlm.default_model` is set. Returned with `error: validation_failed`.
- `502` — An upstream system failed. Check `error` to know which: - `rtvi_vlm_unavailable` — RTVI VLM is unreachable or rejected the request at the HTTP layer. - `rtvi_stream_not_readable` — RTVI accepted the call but the RTSP source could not be opened in time (camera offline, bad URL, codec mismatch, ...). - `rtvi_invalid_response` — RTVI accepted the stream but did not return a stream id; the rule cannot be managed. - `elasticsearch_write_failed` — failed to persist the rule to Elasticsearch.
- `503` — A replay is currently re-onboarding rules onto RTVI. New rules cannot be created until it finishes. Returned with `error: replay_in_progress`.

---

[API](https://skmtc.dev/nvidia/apis/alert-agent-api.md) · [All operations](https://skmtc.dev/nvidia/apis/alert-agent-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nvidia/alert-agent-api/revisions/e754ab3efedd/schema)