Skip to navigation
System ComponentsVision MicroservicesReal-Time VLM

API Reference

View as Markdown

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:

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

MethodEndpointSummary
GET/v1/metricsGet RTVI metrics

Health Check

MethodEndpointSummary
GET/v1/readyGet RTVI VLM Microservice readiness status
GET/v1/liveGet RTVI VLM Microservice liveness status
GET/v1/startupGet RTVI VLM Microservice startup status
GET/v1/assets/statsGet asset storage statistics

Metadata

MethodEndpointSummary
GET/v1/metadataGet RTVI VLM Microservice metadata

Files

MethodEndpointSummary
POST/v1/filesAPI for uploading a media file
GET/v1/filesReturns 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}/contentReturns the contents of the specified file

Live Stream

MethodEndpointSummary
POST/v1/streams/addAdd live stream(s)
GET/v1/streams/get-stream-infoList all live streams
DELETE/v1/streams/delete/{stream_id}Remove a live stream
DELETE/v1/streams/delete-batchRemove multiple live streams
DELETE/v1/generate_captions/{stream_id}Stop a live stream from generating captions and alerts

Config

MethodEndpointSummary
POST/v1/configUpdate runtime message bus configuration

Stream

MethodEndpointSummary
POST/v1/stream/addAdd a video stream
POST/v1/stream/removeRemove a video stream
GET/v1/stream/get-stream-infoList all streams

Models

MethodEndpointSummary
GET/v1/modelsLists the currently available models, and provides basic information about each one such as the owner and availability

Captions

MethodEndpointSummary
POST/v1/generate_captionsGenerate VLM captions and audio transcripts for a video with alerts

NIM Compatible

MethodEndpointSummary
POST/v1/chat/completionsOpenAI-compatible chat endpoint
POST/v1/completionsOpenAI-compatible completions endpoint
GET/v1/versionVersion
GET/v1/manifestManifest
GET/v1/health/liveHealth Live (NIM compatible)
GET/v1/health/readyHealth Ready (NIM compatible)

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