> This page is for version Dev.
> For other versions, use one of these documentation indexes:
> - 3.3.0 (default): https://docs.nvidia.com/vss/3.3.0/llms.txt
> - Dev: https://docs.nvidia.com/vss/dev/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/vss/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/vss/_mcp/server.

# API Reference

This page provides API reference for the Real-Time VLM Microservice.

## Base URL

For a VSS developer-profile deployment, the API is available at:

* **REST API**: `http://<host>:${RTVI_VLM_PORT:-8018}`

The profile maps that host port to port `8000` in the RTVI-VLM container. A
standalone RTVI-VLM Compose deployment instead publishes the required
`BACKEND_PORT` value; the standalone setup example sets it to `8000`.

All endpoints are prefixed with `/v1`.

## Authentication

The API supports Bearer token authentication. Include your token in the `Authorization` header:

```bash
Authorization: Bearer <your-token>
```

## API Categories

The RTVI-VLM API is organized into the following categories:

* **Captions**: Generate VLM captions and alerts for videos and live streams
* **Files**: Upload and manage video/image files
* **Live Stream**: Add, list, and manage RTSP live streams
* **Stream**: CV-compatible stream add, remove, and list APIs
* **Config**: Update generated-message and error-message output routing
* **Models**: List available VLM models
* **Health Check**: Service health and readiness probes
* **Metrics**: Prometheus metrics endpoint
* **Metadata**: Service metadata and version information
* **NIM Compatible**: OpenAI-compatible endpoints for interoperability

## Endpoint catalog

### Metrics

| Method | Endpoint      | Summary          |
| ------ | ------------- | ---------------- |
| `GET`  | `/v1/metrics` | Get RTVI metrics |

### Health Check

| Method | Endpoint           | Summary                                    |
| ------ | ------------------ | ------------------------------------------ |
| `GET`  | `/v1/ready`        | Get RTVI VLM Microservice readiness status |
| `GET`  | `/v1/live`         | Get RTVI VLM Microservice liveness status  |
| `GET`  | `/v1/startup`      | Get RTVI VLM Microservice startup status   |
| `GET`  | `/v1/assets/stats` | Get asset storage statistics               |

### Metadata

| Method | Endpoint       | Summary                            |
| ------ | -------------- | ---------------------------------- |
| `GET`  | `/v1/metadata` | Get RTVI VLM Microservice metadata |

### Files

| Method   | Endpoint                      | Summary                                    |
| -------- | ----------------------------- | ------------------------------------------ |
| `POST`   | `/v1/files`                   | API for uploading a media file             |
| `GET`    | `/v1/files`                   | Returns list of files                      |
| `DELETE` | `/v1/files/{file_id}`         | Delete a file                              |
| `GET`    | `/v1/files/{file_id}`         | Returns information about a specific file  |
| `GET`    | `/v1/files/{file_id}/content` | Returns the contents of the specified file |

### Live Stream

| Method   | Endpoint                            | Summary                                                |
| -------- | ----------------------------------- | ------------------------------------------------------ |
| `POST`   | `/v1/streams/add`                   | Add live stream(s)                                     |
| `GET`    | `/v1/streams/get-stream-info`       | List all live streams                                  |
| `DELETE` | `/v1/streams/delete/{stream_id}`    | Remove a live stream                                   |
| `DELETE` | `/v1/streams/delete-batch`          | Remove multiple live streams                           |
| `DELETE` | `/v1/generate_captions/{stream_id}` | Stop a live stream from generating captions and alerts |

### Config

| Method | Endpoint     | Summary                                  |
| ------ | ------------ | ---------------------------------------- |
| `POST` | `/v1/config` | Update runtime message bus configuration |

### Stream

| Method | Endpoint                     | Summary               |
| ------ | ---------------------------- | --------------------- |
| `POST` | `/v1/stream/add`             | Add a video stream    |
| `POST` | `/v1/stream/remove`          | Remove a video stream |
| `GET`  | `/v1/stream/get-stream-info` | List all streams      |

### Models

| Method | Endpoint     | Summary                                                                                                                |
| ------ | ------------ | ---------------------------------------------------------------------------------------------------------------------- |
| `GET`  | `/v1/models` | Lists the currently available models, and provides basic information about each one such as the owner and availability |

### Captions

| Method | Endpoint                | Summary                                                             |
| ------ | ----------------------- | ------------------------------------------------------------------- |
| `POST` | `/v1/generate_captions` | Generate VLM captions and audio transcripts for a video with alerts |

### NIM Compatible

| Method | Endpoint               | Summary                                |
| ------ | ---------------------- | -------------------------------------- |
| `POST` | `/v1/chat/completions` | OpenAI-compatible chat endpoint        |
| `POST` | `/v1/completions`      | OpenAI-compatible completions endpoint |
| `GET`  | `/v1/version`          | Version                                |
| `GET`  | `/v1/manifest`         | Manifest                               |
| `GET`  | `/v1/health/live`      | Health Live (NIM compatible)           |
| `GET`  | `/v1/health/ready`     | Health Ready (NIM compatible)          |

The machine-readable OpenAPI specification is `services/rtvi/rt-vlm/api_spec/openapi.json` in this repository.