> 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 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:

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

## Endpoint catalog

### Metrics

| Method | Endpoint   | Summary                            |
| ------ | ---------- | ---------------------------------- |
| `GET`  | `/metrics` | Get Video Summarization MS metrics |

### Health Check

| Method | Endpoint       | Summary                                     |
| ------ | -------------- | ------------------------------------------- |
| `GET`  | `/v1/live`     | Get Video Summarization MS liveness status  |
| `GET`  | `/v1/ready`    | Get Video Summarization MS readiness status |
| `GET`  | `/v1/startup`  | Get Video Summarization MS startup status   |
| `GET`  | `/v1/healthz`  | Get service health status                   |
| `GET`  | `/v1/metadata` | Get Video Summarization MS service metadata |

### Models

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

### Summarization

| Method | Endpoint        | Summary                |
| ------ | --------------- | ---------------------- |
| `POST` | `/v1/summarize` | Summarize a video file |
| `POST` | `/summarize`    | Summarize 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

| Method | Endpoint                | Summary                 |
| ------ | ----------------------- | ----------------------- |
| `POST` | `/v1/generate_captions` | Start stream captioning |
| `POST` | `/v1/stream_summarize`  | Summarize a stream      |

### Question Answering

| Method | Endpoint               | Summary                                 |
| ------ | ---------------------- | --------------------------------------- |
| `POST` | `/v1/chat/completions` | Ask a question about a summarized video |

### Asset Management

| Method   | Endpoint                   | Summary                                     |
| -------- | -------------------------- | ------------------------------------------- |
| `DELETE` | `/assets/{asset_id}/index` | Delete 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.

### Recommended Config

| Method | Endpoint              | Summary                      |
| ------ | --------------------- | ---------------------------- |
| `POST` | `/recommended_config` | Recommend config for a video |

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