Skip to navigation
System ComponentsVision MicroservicesVideo Summarization

API Reference

View as Markdown

This page provides API reference for the Video Summarization microservice.

Base URL

The API is available at:

  • REST API: http://<host>:38111
  • MCP Server: http://<host>:38112

Endpoints listed below with a /v1 prefix are always served at that path. The rest are served at the root by default and gain a /v1 prefix when VSS_API_ENABLE_VERSIONING is enabled.

Authentication

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

Authorization: Bearer <your-token>

Endpoint catalog

Metrics

MethodEndpointSummary
GET/metricsGet Video Summarization MS metrics

Health Check

MethodEndpointSummary
GET/v1/liveGet Video Summarization MS liveness status
GET/v1/readyGet Video Summarization MS readiness status
GET/v1/startupGet Video Summarization MS startup status
GET/v1/healthzGet service health status
GET/v1/metadataGet Video Summarization MS service metadata

Models

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

Summarization

MethodEndpointSummary
POST/v1/summarizeSummarize a video file
POST/summarizeSummarize a video file

/v1/summarize is always registered. /summarize is served as well while VSS_API_ENABLE_VERSIONING is disabled, which is the default.

Both reject a request with HTTP 422 when the media offsets are reversed (start later than end) or when min_tokens is greater than max_tokens.

Stream

MethodEndpointSummary
POST/v1/generate_captionsStart stream captioning
POST/v1/stream_summarizeSummarize a stream

Question Answering

MethodEndpointSummary
POST/v1/chat/completionsAsk a question about a summarized video

Asset Management

MethodEndpointSummary
DELETE/assets/{asset_id}/indexDelete the Elasticsearch index for an asset

Each summarization request creates one default_<asset_id> Elasticsearch index with one shard. The default Compose configuration sets LVS_DISABLE_DB_RESET_ON_REQUEST_DONE=true, which retains the index after a file summarization request completes. Set the variable to false to drop the index automatically when file summarization completes. If the variable is not set in the service process, the code defaults to false.

Live-stream summarization retains its index regardless of this setting because consecutive /v1/stream_summarize calls reuse the same asset ID. Use this endpoint to reclaim a retained index and avoid exhausting the per-node shard cap. The call is idempotent, so a missing index is not an error.

MethodEndpointSummary
POST/recommended_configRecommend config for a video

The machine-readable OpenAPI specification is services/video-summarization/api_spec/openapi.json in this repository.