---
title: "Start stream captioning"
method: POST
path: "/v1/generate_captions"
tags: ["Stream"]
---

# Start stream captioning

`POST /v1/generate_captions`

Fire-and-forget: kicks off VLM captioning on RTVI for a stream that was previously added via RTVI stream/add. Returns immediately once RTVI acknowledges the request.

## Request body

- GenerateCaptionsRequest — Request body for POST /v1/generate_captions (stream captioning).
  - `id` string, uuid, required — Stream ID (from RTVI stream/add).
  - `model` string, required — Model to use for caption generation.
  - `prompt` string — VLM prompt for caption generation.
  - `system_prompt` string — System prompt for the VLM.
  - `chunk_duration` integer — Chunk videos into chunkDuration seconds. 0 for no chunking.
  - `chunk_overlap_duration` integer — Chunk overlap duration in seconds. 0 for no overlap.
  - `num_frames_per_second_or_fixed_frames_chunk` number, nullable — Number of frames per second or fixed frames per chunk.
  - `use_fps_for_chunking` boolean — Use FPS for chunking instead of fixed frame count.
  - `max_tokens` integer, nullable — Maximum number of tokens to generate per chunk.
  - `temperature` number, nullable — Sampling temperature for VLM text generation.
  - `top_p` number, nullable — Top-p sampling mass for VLM text generation.
  - `top_k` number, nullable — Top-k filtering for VLM text generation.
  - `seed` integer, nullable — Seed value for reproducibility.
  - `enable_reasoning` boolean — Enable reasoning for VLM captions generation.
  - `enable_audio` boolean — Enable audio ASR alongside video captioning.
  - `vlm_input_width` integer — VLM input width (0 = model default).
  - `vlm_input_height` integer — VLM input height (0 = model default).
  - `mm_processor_kwargs` object, nullable — Optional multimodal processor kwargs.
  - `alert_category` string, nullable — Alert category for structured captioning.
  - `creation_time` string, nullable — ISO 8601 creation timestamp for the stream.
  - `scenario` string — Scenario description for auto-prompt generation.
  - `events` string[] — Event types for auto-prompt generation.
  - `objects_of_interest` string[] — Objects of interest for auto-prompt generation.
  - `enable_vlm_structured_output` boolean — Enable structured VLM output (controls auto-prompt format).
  - `override_vlm_prompt` boolean — If true, use prompt as-is instead of auto-generating from scenario/events.

## Response `200`

Captioning started.

- GenerateCaptionsResponse — Response for POST /v1/generate_captions.
  - `id` string, required — Stream ID that captioning was started for.
  - `status` string, required — Status of the captioning request.
  - `model` string, required — Model used for caption generation.

## 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.

---

[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)