> This page is for version v1.3 (default). > For other versions, use one of these documentation indexes: > - v1.3 (default): https://docs.twelvelabs.io/v1.3/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.twelvelabs.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.twelvelabs.io/_mcp/server. The `TwelveLabs` class provides methods to analyze videos synchronously and generate text based on their content. These methods return results immediately in the response. **When to use these methods**: * Analyze videos up to 1 hour, or images * Retrieve immediate results without polling for task completion * Stream text fragments in real time for immediate processing and feedback **Do not use these methods for**: * Videos longer than 1 hour. Use the [`analyze_async.tasks.create`](/v1.3/sdk-reference/python/analyze-videos/async-analysis#create-an-async-analysis-task) method instead. * Video segmentation with custom segment definitions. Use the [`analyze_async.tasks.create`](/v1.3/sdk-reference/python/analyze-videos/async-analysis#create-an-async-analysis-task) method instead. # Sync analysis **Description**: This method analyzes a video or one or more images and returns the results directly in the response. Each request must contain a video or one or more images, but not both. You can use general analysis (prompt-based text generation) with either media type. #### Input requirements **Videos** * Minimum duration: 1 second * Maximum duration: 1 hour * Formats: [FFmpeg supported formats](https://ffmpeg.org/ffmpeg-formats.html) * Resolution: 360x360 to 5184x2160 pixels * Aspect ratio: Between 1:1 and 1:2.4, or between 2.4:1 and 1:1. **Images** * You can provide one to twenty images per request. * Formats: JPEG, PNG, WebP, GIF, and BMP. * Maximum size: 20 MB per image. * Maximum pixel count: 16,777,216 pixels per image (width × height). On the Free plan in legacy billing, you have a total of 600 minutes (10 hours) shared across indexing, analysis, and segmentation. For details, see the [Video hours and video count limits](/v1.3/docs/concepts/indexes#video-hours-and-video-count-limits) section. In the new billing, the allowances of your plan apply in place of this limit. See [Plans, allowances, and overage](/v1.3/docs/get-started/plans-and-billing/plans-allowances-and-overage). > **Note** > > This method is rate-limited. For details, see the [Rate limits](/v1.3/docs/get-started/rate-limits) page. **Function signature and example**: **`Function signature`** ```python Function signature def analyze( self, *, model_name: typing.Optional[AnalyzeRequestModelName] = OMIT, video: typing.Optional[VideoContext] = OMIT, image: typing.Optional[typing.Sequence[AnalyzeImageInput]] = OMIT, prompt: typing.Optional[AnalyzeTextPrompt] = OMIT, prompt_v_2: typing.Optional[AnalyzePromptV2] = OMIT, temperature: typing.Optional[AnalyzeTemperature] = OMIT, response_format: typing.Optional[SyncResponseFormat] = OMIT, max_tokens: typing.Optional[int] = OMIT, start_time: typing.Optional[float] = OMIT, end_time: typing.Optional[float] = OMIT, request_options: typing.Optional[RequestOptions] = None, ) -> NonStreamAnalyzeResponse: ``` **`Python example`** ```python Python example from twelvelabs import TwelveLabs from twelvelabs.types import VideoContext_Url, AnalyzePromptV2, SmeMediaSource result = client.analyze( model_name="pegasus1.5", video=VideoContext_Url(url=""), prompt_v_2=AnalyzePromptV2( input_text="", # To use reference images: "Is there a <@product> in this video?" # media_sources=[ # SmeMediaSource(name="product", media_type="image", url=""), # ], ), temperature=0.2 ) print("Result ID:", result.id) print(f"Generated Text: {result.data}") if result.usage is not None: print(f"Output tokens: {result.usage.output_tokens}") ``` **`Image input example`** ```python Image input example from twelvelabs import TwelveLabs from twelvelabs.types import AnalyzeImageInput result = client.analyze( model_name="pegasus1.6", image=[ AnalyzeImageInput( name="product_shot", url="", ), ], prompt="Describe the product in <@product_shot> and list every visible feature.", ) print("Result ID:", result.id) print(f"Generated Text: {result.data}") ``` **Parameters**: | Name | Type | Required | Description | | :---------------- | :---------------------------------------------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `model_name` | `typing.Optional[AnalyzeRequestModelName]` | No | The video understanding model to use for analysis. Values: - `"pegasus1.6"`: For details about this version, see the [Pegasus 1.6](/v1.3/docs/concepts/models/pegasus/pegasus-1-6) page. - `"pegasus1.5"`: For details about this version, see the [Pegasus 1.5](/v1.3/docs/concepts/models/pegasus/pegasus-1-5) page. **Default:** `"pegasus1.5"` | | `video` | `typing.Optional[VideoContext]` | No | An object specifying the source of the video content. Include exactly one source. Mutually exclusive with the `image` parameter. See [VideoContext](#videocontext). | | `image` | `typing.Optional[typing.Sequence[AnalyzeImageInput]]` | No | A list of up to twenty objects containing the images to analyze. For each image, include exactly one source. Requires Pegasus 1.6. Using any other model returns a `parameter_invalid` error. Mutually exclusive with the `video` and `prompt_v_2` parameters. The `prompt` parameter is required when you provide images. See [AnalyzeImageInput](#analyzeimageinput) for details. | | `prompt` | `typing.Optional[str]` | No | A text prompt that guides the model on the desired format or content. To include reference images in your prompt, use the `prompt_v_2` parameter instead. Mutually exclusive with the `prompt_v_2` parameter. | | `prompt_v_2` | `typing.Optional[AnalyzePromptV2]` | No | A structured prompt that uses the `<@name>` placeholders to reference images. Mutually exclusive with the `prompt` and `image` parameters. See [AnalyzePromptV2](#analyzepromptv2). | | `temperature` | `typing.Optional[float]` | No | Controls the randomness of the text output. **Default:** 0.2, **Min:** 0, **Max:** 1 | | `start_time` | `typing.Optional[float]` | No | Start of the analysis window, as an absolute timestamp in seconds, based on the internal metadata of the video. Use with `end_time` to analyze only a portion of the video. If omitted, defaults to the internal start time of the video. Most videos start at 0, but some (for example, from cameras or broadcast recordings) may have a non-zero start time. To find the value, run `ffprobe -v error -show_entries format=start_time,duration -of default=noprint_wrappers=1 your_video.mp4`. Must be less than `end_time` and the video duration. The window (`end_time - start_time`) must be at least 1 second. | | `end_time` | `typing.Optional[float]` | No | End of the analysis window, as an absolute timestamp in seconds, based on the internal metadata of the video. Use with `start_time` to analyze only a portion of the video. If omitted, defaults to the internal start time of the video plus its duration. Most videos start at 0, but some (for example, from cameras or broadcast recordings) may have a non-zero start time. To find the value, run `ffprobe -v error -show_entries format=start_time,duration -of default=noprint_wrappers=1 your_video.mp4`. Must be greater than `start_time` and less than or equal to the video duration. The window (`end_time - start_time`) must be at least 1 second. | | `request_options` | `typing.Optional[RequestOptions]` | No | Request-specific configuration. | The `SyncResponseFormat` class contains the following properties: | Name | Type | Description | | ------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` | `SyncResponseFormatType` | The response format to use. Value: `"json_schema"` (structured JSON conforming to a provided schema). | | `json_schema` | `Dict[str, Optional[Any]]` | Contains the JSON schema that defines the response structure. The schema must adhere to the [JSON Schema Draft 2020-12](https://json-schema.org/draft/2020-12) specification. For details, see the [`json_schema`](/v1.3/api-reference/analyze-videos/sync-analysis#request.body.response_format.json_schema) parameter in the API Reference section. | ### VideoContext The `VideoContext` type specifies the source of the video content. Provide exactly one of the following: | Class | Field | Type | Description | | --------------------------- | ---------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `VideoContext_Url` | `url` | `str` | The publicly accessible URL of the video file or HLS manifest. Use direct links to raw media files, or the URL of a VOD HLS manifest. Live video streams are rejected with a `400` error. Video hosting platforms and cloud storage sharing links are not supported. For HLS sources, if the duration cannot be determined, the platform calculates it from the manifest and the duration limits apply to that value. | | `VideoContext_AssetId` | `asset_id` | `str` | The unique identifier of an asset from a [direct](/v1.3/sdk-reference/python/upload-content/direct-uploads) or [multipart](/v1.3/sdk-reference/python/upload-content/multipart-uploads) upload. The asset status must be `ready`. Use [`assets.retrieve`](/v1.3/sdk-reference/python/manage-assets#retrieve-an-asset) to check the status. | | `VideoContext_Base64String` | `base_64_string` | `str` | The base64-encoded video data. The maximum size is 30MB. | ### AnalyzeImageInput The `AnalyzeImageInput` class defines an image to analyze. Provide exactly one of the `url`, `asset_id`, or `base64_string` fields. | Name | Type | Required | Description | | ---------------- | --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | `str` | Yes | The name of this image. Must be unique within the `image` array. Can contain only letters, digits, and underscores. To refer to a specific image in your prompt, use its name as the `<@name>` placeholder. Reference every image or none of them: - If the prompt references every image, the platform analyzes each one (Example: `Compare <@before> with <@after> and describe what changed.`). - If the prompt references none of them, the platform analyzes every image you provided (Example: `List every visible feature in these images.`). - If the prompt references only some of the images, the platform returns a `400` error. | | `url` | `Optional[str]` | No | A publicly accessible HTTPS URL of the image. The platform rejects HTTP URLs. When you send the request, the platform verifies that the URL is reachable and that the image is within the [size, pixel count, and format limits](/v1.3/docs/concepts/models/pegasus/pegasus-1-6#image-file-requirements). If either check fails, the platform returns a `400` error. | | `asset_id` | `Optional[str]` | No | The unique identifier of an uploaded asset. | | `base_64_string` | `Optional[str]` | No | Base64-encoded image data. The maximum decoded size is 20 MB. Supported image types: `image/jpeg`, `image/png`, `image/webp`, `image/gif`, and `image/bmp`. Standard and unpadded base64 encodings are both accepted. | ### AnalyzePromptV2 The `AnalyzePromptV2` class defines a structured prompt that uses `<@name>` placeholders to reference images. Mutually exclusive with the `prompt` and `image` parameters. | Name | Type | Required | Description | | --------------- | -------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `input_text` | `str` | Yes | The text of the prompt. Use `<@name>` placeholders to reference images declared in `media_sources` (Example: `"Is there a <@tiger-1> in the video?"`). This text counts toward the [context window](/v1.3/docs/concepts/models/pegasus/pegasus-1-6#context-window). | | `media_sources` | `Optional[List[SmeMediaSource]]` | No | Reference images for the `<@name>` placeholders in the prompt. Maximum 4 sources. See [SmeMediaSource](#smemediasource). | ### SmeMediaSource A reference image that provides visual context. Provide exactly one of the `url`, `asset_id`, or `base_64_string` fields. | Name | Type | Required | Description | | ---------------- | ------------------------- | -------- | ------------------------------------------------------------- | | `name` | `str` | Yes | A descriptive name for this media source. | | `media_type` | `SmeMediaSourceMediaType` | Yes | The media type. Value: `"image"`. | | `url` | `Optional[str]` | No | A publicly accessible HTTPS URL of the image. | | `asset_id` | `Optional[str]` | No | The unique identifier of an uploaded asset. | | `base_64_string` | `Optional[str]` | No | Base64-encoded image data. The maximum decoded size is 32 MB. | **Return value**: Returns a `NonStreamAnalyzeResponse` object containing the generated text. The `NonStreamAnalyzeResponse` class contains the following properties: | Name | Type | Description | | --------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | `Optional[str]` | Unique identifier of the response. | | `data` | `Optional[str]` | The generated text based on the prompt you provided. | | `finish_reason` | `typing.Optional[FinishReason]` | The reason the generation stopped. Values: - `null`: The generation has not finished yet. - `"stop"`: The generation reached the end of the output text. - `"length"`: The generation reached the maximum response length or the [context window](/v1.3/docs/concepts/models/pegasus/pegasus-1-6#context-window). When you set the `response_format` parameter, the output may be truncated and fail to parse. The partial output is in `data`, and a warning is in the `error` field. | | `usage` | `Optional[TokenUsage]` | The number of tokens used in the generation. | The `TokenUsage` class contains the following properties: | Name | Type | Description | | --------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `output_tokens` | `int` | The number of tokens in the generated text. | | `input_tokens` | `Optional[int]` | The number of tokens the input consumed. Together with `output_tokens`, this value must fit within the [context window](/v1.3/docs/concepts/models/pegasus/pegasus-1-6#context-window). | **API Reference**: [Sync analysis](/v1.3/api-reference/analyze-videos/sync-analysis). **Related guide**: [Analyze videos and images](/v1.3/docs/guides/analyze-videos-and-images). # Sync analysis with streaming responses **Description**: This method analyzes a video or one or more images and returns the results directly in the response. Each request must contain a video or one or more images, but not both. You can use general analysis (prompt-based text generation) with either media type. #### Input requirements **Videos** * Minimum duration: 1 second * Maximum duration: 1 hour * Formats: [FFmpeg supported formats](https://ffmpeg.org/ffmpeg-formats.html) * Resolution: 360x360 to 5184x2160 pixels * Aspect ratio: Between 1:1 and 1:2.4, or between 2.4:1 and 1:1. **Images** * You can provide one to twenty images per request. * Formats: JPEG, PNG, WebP, GIF, and BMP. * Maximum size: 20 MB per image. * Maximum pixel count: 16,777,216 pixels per image (width × height). On the Free plan in legacy billing, you have a total of 600 minutes (10 hours) shared across indexing, analysis, and segmentation. For details, see the [Video hours and video count limits](/v1.3/docs/concepts/indexes#video-hours-and-video-count-limits) section. In the new billing, the allowances of your plan apply in place of this limit. See [Plans, allowances, and overage](/v1.3/docs/get-started/plans-and-billing/plans-allowances-and-overage). > **Note** > > This method is rate-limited. For details, see the [Rate limits](/v1.3/docs/get-started/rate-limits) page. **Function signature and example**: **`Function signature`** ```python Function signature def analyze_stream( self, *, model_name: typing.Optional[AnalyzeStreamRequestModelName] = OMIT, video: typing.Optional[VideoContext] = OMIT, image: typing.Optional[typing.Sequence[AnalyzeImageInput]] = OMIT, prompt: typing.Optional[AnalyzeTextPrompt] = OMIT, prompt_v_2: typing.Optional[AnalyzePromptV2] = OMIT, temperature: typing.Optional[AnalyzeTemperature] = OMIT, response_format: typing.Optional[SyncResponseFormat] = OMIT, max_tokens: typing.Optional[int] = OMIT, start_time: typing.Optional[float] = OMIT, end_time: typing.Optional[float] = OMIT, request_options: typing.Optional[RequestOptions] = None, ) -> typing.Iterator[StreamAnalyzeResponse] ``` **`Python example`** ```python Python example from twelvelabs import TwelveLabs from twelvelabs.types import VideoContext_Url, AnalyzePromptV2, SmeMediaSource response = client.analyze_stream( model_name="pegasus1.5", video=VideoContext_Url(url=""), prompt_v_2=AnalyzePromptV2( input_text="", # To use reference images: "Is there a <@product> in this video?" # media_sources=[ # SmeMediaSource(name="product", media_type="image", url=""), # ], ), temperature=0.2, ) for chunk in response: if hasattr(chunk, 'event_type'): if chunk.event_type == "stream_start": print("Stream started") elif chunk.event_type == "text_generation": print(chunk.text, end="") elif chunk.event_type == "stream_end": print("\nStream ended") if chunk.metadata: print(f"Metadata: {chunk.metadata}") ``` **`Image input example`** ```python Image input example from twelvelabs import TwelveLabs from twelvelabs.types import AnalyzeImageInput response = client.analyze_stream( model_name="pegasus1.6", image=[ AnalyzeImageInput( name="product_shot", url="", ), ], prompt="Describe the product in <@product_shot> and list every visible feature.", ) for chunk in response: if hasattr(chunk, 'event_type'): if chunk.event_type == "stream_start": print("Stream started") elif chunk.event_type == "text_generation": print(chunk.text, end="") elif chunk.event_type == "stream_end": print("\nStream ended") ``` **Parameters**: | Name | Type | Required | Description | | :---------------- | :---------------------------------------------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `model_name` | `typing.Optional[AnalyzeRequestModelName]` | No | The video understanding model to use for analysis. Values: - `"pegasus1.6"`: For details about this version, see the [Pegasus 1.6](/v1.3/docs/concepts/models/pegasus/pegasus-1-6) page. - `"pegasus1.5"`: For details about this version, see the [Pegasus 1.5](/v1.3/docs/concepts/models/pegasus/pegasus-1-5) page. **Default:** `"pegasus1.5"` | | `video` | `typing.Optional[VideoContext]` | No | An object specifying the source of the video content. Include exactly one source. Mutually exclusive with the `image` parameter. See [VideoContext](#videocontext). | | `image` | `typing.Optional[typing.Sequence[AnalyzeImageInput]]` | No | A list of up to twenty objects containing the images to analyze. For each image, include exactly one source. Requires Pegasus 1.6. Using any other model returns a `parameter_invalid` error. Mutually exclusive with the `video` and `prompt_v_2` parameters. The `prompt` parameter is required when you provide images. See [AnalyzeImageInput](#analyzeimageinput) for details. | | `prompt` | `typing.Optional[str]` | No | A text prompt that guides the model on the desired format or content. To include reference images in your prompt, use the `prompt_v_2` parameter instead. Mutually exclusive with the `prompt_v_2` parameter. | | `prompt_v_2` | `typing.Optional[AnalyzePromptV2]` | No | A structured prompt that uses the `<@name>` placeholders to reference images. Mutually exclusive with the `prompt` and `image` parameters. See [AnalyzePromptV2](#analyzepromptv2). | | `temperature` | `typing.Optional[float]` | No | Controls the randomness of the text output. **Default:** 0.2, **Min:** 0, **Max:** 1 | | `start_time` | `typing.Optional[float]` | No | Start of the analysis window, as an absolute timestamp in seconds, based on the internal metadata of the video. Use with `end_time` to analyze only a portion of the video. If omitted, defaults to the internal start time of the video. Most videos start at 0, but some (for example, from cameras or broadcast recordings) may have a non-zero start time. To find the value, run `ffprobe -v error -show_entries format=start_time,duration -of default=noprint_wrappers=1 your_video.mp4`. Must be less than `end_time` and the video duration. The window (`end_time - start_time`) must be at least 1 second. | | `end_time` | `typing.Optional[float]` | No | End of the analysis window, as an absolute timestamp in seconds, based on the internal metadata of the video. Use with `start_time` to analyze only a portion of the video. If omitted, defaults to the internal start time of the video plus its duration. Most videos start at 0, but some (for example, from cameras or broadcast recordings) may have a non-zero start time. To find the value, run `ffprobe -v error -show_entries format=start_time,duration -of default=noprint_wrappers=1 your_video.mp4`. Must be greater than `start_time` and less than or equal to the video duration. The window (`end_time - start_time`) must be at least 1 second. | | `request_options` | `typing.Optional[RequestOptions]` | No | Request-specific configuration. | For details about `VideoContext`, `AnalyzeImageInput`, `AnalyzePromptV2`, and `SmeMediaSource`, see the [Sync analysis](#sync-analysis) section above. The `SyncResponseFormat` class contains the following properties: | Name | Type | Description | | ------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` | `SyncResponseFormatType` | The response format to use. Value: `"json_schema"` (structured JSON conforming to a provided schema). | | `json_schema` | `Dict[str, Optional[Any]]` | Contains the JSON schema that defines the response structure. The schema must adhere to the [JSON Schema Draft 2020-12](https://json-schema.org/draft/2020-12) specification. For details, see the [`json_schema`](/v1.3/api-reference/analyze-videos/sync-analysis#request.body.response_format.json_schema) parameter in the API Reference section. | **Return value**: Returns an iterator of `StreamAnalyzeResponse` objects. Each response can be a `StreamAnalyzeResponse_StreamStart`, `StreamAnalyzeResponse_TextGeneration`, or `StreamAnalyzeResponse_StreamEnd`. The `StreamAnalyzeResponse_StreamStart` class contains the following properties: | Name | Type | Description | | ------------ | --------------------------------------- | ---------------------------------------------------------- | | `event_type` | `typing.Literal["stream_start"]` | This field is always set to `stream_start` for this event. | | `metadata` | `Optional[StreamStartResponseMetadata]` | An object containing metadata about the stream. | The `StreamAnalyzeResponse_TextGeneration` class contains the following properties: | Name | Type | Description | | ------------ | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `event_type` | `typing.Literal["text_generation"]` | This field is always set to `text_generation` for this event. | | `text` | `Optional[str]` | A fragment of the generated text. Text fragments may be split at arbitrary points, not necessarily at word or sentence boundaries. | The `StreamAnalyzeResponse_StreamEnd` class contains the following properties: | Name | Type | Description | | --------------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `event_type` | `typing.Literal["stream_end"]` | This field is always set to `stream_end` for this event. | | `finish_reason` | `typing.Optional[FinishReason]` | The reason the generation stopped. Values: - `null`: The generation has not finished yet. - `"stop"`: The generation reached the end of the output text. - `"length"`: The generation reached the maximum response length or the [context window](/v1.3/docs/concepts/models/pegasus/pegasus-1-6#context-window). When you set the `response_format` parameter, the output may be truncated and fail to parse. The partial output is in `data`, and a warning is in the `error` field. | | `metadata` | `typing.Optional[StreamEndResponseMetadata]` | An object containing metadata about the stream. | The `StreamStartResponseMetadata` class contains the following properties: | Name | Type | Description | | --------------- | --------------- | ----------------------------------------------- | | `generation_id` | `Optional[str]` | A unique identifier for the generation session. | The `StreamEndResponseMetadata` class contains the following properties: | Name | Type | Description | | --------------- | ---------------------- | ---------------------------------------------------------------- | | `generation_id` | `Optional[str]` | The same unique identifier provided in the `stream_start` event. | | `usage` | `Optional[TokenUsage]` | The number of tokens used in the generation. | The `TokenUsage` class contains the following properties: | Name | Type | Description | | --------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `output_tokens` | `int` | The number of tokens in the generated text. | | `input_tokens` | `Optional[int]` | The number of tokens the input consumed. Together with `output_tokens`, this value must fit within the [context window](/v1.3/docs/concepts/models/pegasus/pegasus-1-6#context-window). | **API Reference**: [Sync analysis](/v1.3/api-reference/analyze-videos/sync-analysis). **Related guide**: [Analyze videos and images](/v1.3/docs/guides/analyze-videos-and-images). # Error codes This section lists the most common error messages you may encounter while analyzing videos. * `token_limit_exceeded` * The request exceeds the [context window](/v1.3/docs/concepts/models/pegasus/pegasus-1-6#context-window) and cannot be processed. Reduce the prompt length, use a shorter video, or lower the `max_tokens` value. * `Live video streams are not supported. Please provide a URL that is not a live stream.` * The URL points to a live HLS stream. Only VOD manifests are supported. Provide the URL of a VOD manifest. * `output truncated: the generation reached the configured max_tokens. The partial output is returned; raise max_tokens if you need a longer response.` * The response reached the maximum response length in `general` mode. The platform returns the partial output and sets `finish_reason` to `"length"`. This message appears in the `error.message` field. * `output truncated: combined input and output tokens reached the model's context limit. The partial output is returned; consider reducing input size (shorter prompt, smaller video clip, fewer media bindings) or lowering max_tokens.` * The request reached the [context window](/v1.3/docs/concepts/models/pegasus/pegasus-1-6#context-window) in `general` mode. The platform returns the partial output and sets `finish_reason` to `"length"`. This message appears in the `error.message` field. * `analysis failed: the time_based_metadata output reached the configured max_tokens before a complete result was produced. Raise max_tokens if it is below the per-model maximum; otherwise narrow the request (fewer segment_definitions or fields, a larger min_segment_duration, or a shorter analysis window).` * The response reached the maximum response length in `time_based_metadata` mode. The task fails with `status` set to `"failed"`, and no partial output is returned. This message appears in the `error.message` field. * `analysis failed: the time_based_metadata output reached the model's context limit (combined input and output tokens) before a complete result was produced. Narrow the request (fewer segment_definitions or fields, a larger min_segment_duration, a shorter analysis window, fewer media bindings) or lower max_tokens to leave more room for the input.` * The request reached the [context window](/v1.3/docs/concepts/models/pegasus/pegasus-1-6#context-window) in `time_based_metadata` mode. The task fails with `status` set to `"failed"`, and no partial output is returned. This message appears in the `error.message` field. * `user_canceled` * An async analysis task was canceled through the task cancellation endpoint. The task has `status` set to `"canceled"`, and no result is returned. * `batch_canceled` * A queued analysis task was canceled because its batch was canceled. The task has `status` set to `"canceled"`, and no result is returned. * `batch_expired` * A queued analysis task was canceled because its batch expired. The task has `status` set to `"canceled"`, and no result is returned. * `batch_processing_timeout` * A processing analysis task failed after reaching its batch's processing deadline. The task has `status` set to `"failed"`, and no result is returned. * `index_not_supported_for_generate` * You can only summarize videos uploaded to an index with an engine from the Pegasus family enabled. For a list of general errors that apply to all endpoints, see the [Error codes](/v1.3/api-reference/error-codes) page.