---
title: "Summarize a stream"
method: POST
path: "/v1/stream_summarize"
tags: ["Stream"]
---

# Summarize a stream

`POST /v1/stream_summarize`

Aggregate existing captions for a stream from the database via CA-RAG and return a structured summary. The stream must have been previously started with /v1/generate_captions.

## Request body

- StreamSummarizeRequest — Request body for POST /v1/stream_summarize (stream summarization).
  - `id` string, uuid, required — Stream ID to summarize.
  - `model` string, required — Model identifier (must match the loaded model).
  - `start_time` number, nullable — Time window start for summarization (seconds, 0 = no filter).
  - `end_time` number, nullable — Time window end for summarization (seconds, 0 = no filter).
  - `enable_vlm_structured_output` boolean — Enable structured VLM output for summarization.
  - `camera_id` string, nullable — Camera / sensor identifier.
  - `summarize_max_tokens` integer, nullable — Max tokens for LLM aggregation.
  - `summarize_temperature` number, nullable — Temperature for LLM aggregation.
  - `summarize_top_p` number, nullable — Top-p for LLM aggregation.
  - `summarize_batch_size` integer, nullable — Batch size for summarization.
  - `schema` string, nullable — Schema for unstructured output format.
  - `batch_response_method` string, nullable — Batch response method for summarization.
  - `auto_generate_prompt` boolean, nullable — Auto-generate summarization prompt from scenario/events.
  - `time_metadata_keys` string[], nullable — Time metadata keys for summarization.
  - `collection_name` string, nullable — External collection name for DB storage.
  - `custom_metadata` object, nullable — Custom metadata for DB storage.
  - `delete_external_collection` boolean — Delete external collection after summarization.

## Response `200`

Successful Response.

- CompletionResponse — Represents a summarization/chat completion response.
  - `id` string, uuid, required — Unique ID for the query
  - `video_id` string, uuid, required — Unique ID for the video
  - `choices` CompletionResponseChoice[], required — A list of chat completion choices. Can be more than one if `n` is greater than 1.
    - `finish_reason` 'stop' | 'length' | 'content_filter' | 'tool_calls', required — The reason the model stopped generating tokens.
    - `index` integer, required — The index of the choice in the list of choices.
    - `message` ChatCompletionResponseMessage, required — A chat completion message generated by the model.
      - `content` string, nullable, required — The contents of the message. For VLM captions API, this field contains a combined response with timestamps for each chunk.
      - `tool_calls` ChatCompletionMessageToolCall[]
        - `type` 'alert', required — Types of tools supported by VIA.
        - `alert` ChatCompletionMessageAlertTool, required — Alert trigerred by VIA.
          - `name` string, required — Name for the alert that was triggered.
          - `ntpTimestamp` string, nullable — NTP timestamp of when the event occurred (for live-streams).
          - `offset` integer — Offset in seconds in the video file when the event occurred (for files).
          - `detectedEvents` string[], required — List of events detected.
          - `details` string, required — Details of the alert.
      - `role` 'assistant', required — The role of the author of this message.
  - `created` integer, required — The Unix timestamp (in seconds) of when the chat completion/summary request was created.
  - `model` string, required — The model used for the chat completion/summarization.
  - `media_info` union, required — Part of the file / live-stream for which this response is applicable.
    - MediaInfoTimeStamp — Media information using offset for live-streams.
      - `type` 'timestamp', required — Information about a segment of live-stream with start and end timestamp.
      - `start_timestamp` string — Timestamp in the video to start processing from
      - `end_timestamp` string — Timestamp in the video to stop processing at
    - MediaInfoOffset — Media information using offset for files.
      - `type` 'offset', required — Information about a segment of media with start and end offsets.
      - `start_offset` integer — Segment start offset in seconds from the beginning of the media.
      - `end_offset` integer — Segment end offset in seconds from the beginning of the media.
  - `object` 'chat.completion' | 'summarization.completion' | 'summarization.progressing' | 'vlm_captions.completion' | 'vlm_captions.progressing', required — Completion object type.
  - `usage` CompletionUsage — An optional field that will only be present when you set `stream_options: {"include_usage": true}` in your request. When present, it contains a null value except for the last chunk which contains the token usage statistics for the entire request.
    - `query_processing_time` integer, required — Summarization Query Processing Time in seconds.
    - `total_chunks_processed` integer, required — Total Number of chunks processed.
    - `summary_tokens` integer — Total Number of tokens used for summary.
    - `aggregation_tokens` integer — Total Number of tokens used for aggregation.
    - `summary_requests` integer — Total Number of requests for summary.
    - `summary_latency` number — Total latency for summary.
    - `aggregation_latency` number — Total latency for aggregation.

## Other responses

- `400` — Bad Request. The server could not understand the request due to invalid syntax.
- `401` — Unauthorized request.
- `422` — Failed to process request.
- `429` — Rate limiting exceeded.
- `500` — Internal Server Error.
- `503` — Server is busy. Client may try again later.

---

[API](https://skmtc.dev/nvidia/apis/long-video-summarization-api.md) · [All operations](https://skmtc.dev/nvidia/apis/long-video-summarization-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nvidia/long-video-summarization-api/revisions/2ce997975112/schema)