---
title: "Sync analysis"
method: POST
path: "/analyze"
tags: [""]
---

# Sync analysis

`POST /analyze`

This method analyzes your videos and returns the results directly in the response. It generates text based on your prompts and supports both Pegasus 1.2 and Pegasus 1.5 for general analysis (prompt-based text generation).

<Accordion title="Input requirements">
- Minimum duration: 4 seconds
- 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.
</Accordion>

**When to use this method**:
- Analyze videos up to 1 hour
- Retrieve immediate results without polling for task completion
- Stream text fragments in real time for immediate processing and feedback

**Do not use this method for**:
- Videos longer than 1 hour. Use the [`POST`](/v1.3/api-reference/analyze-videos/create-async-analysis-task) method of the `/analyze/tasks` endpoint instead.
- Video segmentation with custom segment definitions. Use the [`POST`](/v1.3/api-reference/analyze-videos/create-async-analysis-task) method of the `/analyze/tasks` endpoint with the `model_name` parameter set to `pegasus1.5` instead.

On the Free plan, 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.

<Note title="Note">
This endpoint is rate-limited. For details, see the [Rate limits](/v1.3/docs/get-started/rate-limits) page.
</Note>

## Headers

- `x-api-key` string, required

## Request body

- object
  - `model_name` 'pegasus1.2' | 'pegasus1.5' — The video understanding model to use for analysis. - `pegasus1.2`: General analysis (prompt-based text generation). - `pegasus1.5`: General analysis (prompt-based text generation) with video clipping, structured prompts with reference images, and video segmentation (async only). See the [Pegasus](/v1.3/docs/concepts/models/pegasus#context-window) page for token limits. **Default:** `pegasus1.2`
  - `video_id` string — The unique identifier of the video to analyze. Use this parameter when the `model_name` parameter is `pegasus1.2`. Not supported with `pegasus1.5`. <Info> This parameter will be deprecated and removed in a future version. Use the [`video`](/v1.3/api-reference/analyze-videos/sync-analysis#request.body.video) parameter instead.</Info>
  - `video` union — An object specifying the source of the video content. Include exactly one source.
    - object — Provide the video via a URL.
      - `type` 'url', required — Discriminator value: url
      - `url` string, uri, required — The publicly accessible URL of the video file. Use direct links to raw media files. Video hosting platforms and cloud storage sharing links are not supported.
    - object — Provide the video via a unique identifier of an asset.
      - `type` 'asset_id', required — Discriminator value: asset_id
      - `asset_id` string, required — The unique identifier of an asset from a [direct](/v1.3/api-reference/upload-content/direct-uploads) or [multipart](/v1.3/api-reference/upload-content/multipart-uploads) upload. The asset status must be `ready`. Use the [Retrieve an asset](/v1.3/api-reference/upload-content/direct-uploads/retrieve) method to check the status.
    - object — Provide the video via base64-encoded data.
      - `type` 'base64_string', required — Discriminator value: base64_string
      - `base64_string` string, required — The base64-encoded video data. The maximum size is 30MB.
  - `prompt` string — A prompt that guides the model on the desired format or content. Your prompts can be instructive or descriptive, or you can phrase them as questions. Pegasus 1.2 limits prompts to 2,000 tokens. For Pegasus 1.5, this text counts toward the [context window](/v1.3/docs/concepts/models/pegasus#context-window). **Examples**: - Based on this video, I want to generate five keywords for SEO (Search Engine Optimization). - I want to generate a description for my video with the following format: Title of the video, followed by a summary in 2-3 sentences, highlighting the main topic, key events, and concluding remarks.
  - `prompt_v2` AnalyzePromptV2 — A structured prompt with `<@name>` placeholders for referencing images. Requires the `model_name` parameter set to `pegasus1.5`. Not supported when the `analysis_mode` parameter is `time_based_metadata`. Mutually exclusive with the `prompt` parameter.
    - `input_text` string, required — The text of the prompt. Use `<@name>` placeholders to reference images declared in `media_sources` (Example: `"Is there a <@tiger-1> in the video?"`). For Pegasus 1.5, this text counts toward the [context window](/v1.3/docs/concepts/models/pegasus#context-window).
    - `media_sources` SMEMediaSource[] — Reference images for the `<@name>` placeholders in the prompt. Maximum 4 sources.
      - `name` string, required — A descriptive name for this media source.
      - `media_type` 'image', required — The media type. Only `image` is available.
      - `url` string, uri — A publicly accessible HTTPS URL of the image.
      - `asset_id` string — The unique identifier of an uploaded asset.
      - `base64_string` string — Base64-encoded image data. The maximum size is 30MB.
  - `temperature` number, double — Controls the randomness of the text output. **Default:** 0.2 **Min:** 0 **Max:** 1
  - `stream` boolean — Set this parameter to `true` to enable streaming responses in the <a href="https://github.com/ndjson/ndjson-spec" target="_blank">NDJSON</a> format. **Default:** `true`
  - `response_format` SyncResponseFormat — Specifies the format of the response. When you omit this parameter, the platform returns unstructured text.
    - `type` 'json_schema', required — Set this parameter to "json_schema" to receive structured JSON responses.
    - `json_schema` SyncResponseFormatJsonSchema, required — 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. **Supported types** - `array` - `boolean` - `integer` - `null` - `number` - `object` - `string` - `timestamp` (Pegasus 1.5 only) **Supported constraints** | Type | Supported keywords | Notes | |------|-------------------|-------| | `integer` | `maximum`, `exclusiveMaximum`, `minimum`, `exclusiveMinimum`. | - `maximum`: Sets the highest allowed value (inclusive).<br/>- `exclusiveMaximum`: Sets the highest allowed value (exclusive).<br/>- `minimum`: Sets the lowest allowed value (inclusive).<br/>- `exclusiveMinimum`: Sets the lowest allowed value (exclusive).<br/>These constraints are supported only for the `integer` type. | | `string` | `pattern`, `format` | - `pattern`: A regular expression that the string must match.<br/>- `format`: Validates predefined formats. It accepts the following values: `uuid`, `date-time`, `date`, and `time`.<br/>See string limitations below. | | `object` | `properties`, `required` | - `properties`: Defines object properties and their schemas. - `required`: Specifies mandatory properties.<br/>See object limitations below. | | `array` | `items`, `minItems` | `minItems` accepts only `0` or `1`.<br/>See array limitations below. | | `timestamp` | `format` | `format` (required): Sets the output format. Accepted values: `seconds`, `hh:mm:ss`, `hh:mm:ss.fff`.<br/>See the **Timestamp type** section below. | **String limitations** When you use the `string` type: - The platform validates strings using only `pattern` and `format`. Including `minLength` or `maxLength` causes a 422 error: "String length constraints (minLength) are not supported." Remove these keywords from your schema. **Object limitations** When you use the `object` type: - The platform does not support the `additionalProperties` keyword. Including it causes a 422 error. Remove it from your schema. - The platform returns properties in declaration order. - Make the first property required. If the first property is optional, the platform moves the first required property to the beginning. **Array limitations** When you use the `array` type: - The platform does not support `uniqueItems` or `maxItems`. Including either keyword causes a 422 error. Remove them from your schema. **Constant and enumerated values** The `const` and `enum` keywords support the following types: - `boolean` - `null` - `number` - `string` **Schema composition** The platform supports only `anyOf` for [schema composition](https://json-schema.org/understanding-json-schema/reference/combining). **Annotations** The platform accepts but ignores JSON schema annotations like `title`, `$comments`, and `description`. **Subschema references** You can reference subschemas using `$ref` with these requirements: - Define subschemas within `$defs`. - Use valid URIs that point to the internal subschema. For details, see the [JSON Schema documentation on $defs](https://json-schema.org/understanding-json-schema/structuring#defs). **Timestamp type (Pegasus 1.5 only)** Declare a property as `{"type": "timestamp", "format": "<format>"}` to control the format of the returned value. The `format` field accepts the following values: | `format` | Example output | Notes | |----------|----------------|-------| | `seconds` | `10.5` | Returns a JSON number in seconds. | | `hh:mm:ss` | `"00:01:23"` | Rounded to the nearest second. Negative values are converted to `"00:00:00"`. | | `hh:mm:ss.fff` | `"00:01:23.500"` | Millisecond precision. | The type of the response depends on the value of the `format` field: `seconds` returns a JSON number, while `hh:mm:ss` and `hh:mm:ss.fff` return a JSON string. *Supported positions* You can declare `timestamp` fields at the top level of your schema or inside objects nested one level within an array: - Top level: `properties.<field_name>` - Inside an array: `properties.<array_field>.items.properties.<field_name>` Declaring `timestamp` outside these positions — deeper nesting, inside `oneOf` / `anyOf` / `allOf`, or inside `$ref` — is not supported and is rejected with HTTP 400. *Validation errors* When `format` is missing or invalid, the platform returns `400 parameter_invalid`: ``` response_format.json_schema.properties.<name>.format: format is required for timestamp type; allowed values: seconds, hh:mm:ss, hh:mm:ss.fff ``` **Reserved property names (`start_time` / `end_time`)** For Pegasus 1.5, properties named `start_time` or `end_time` in your response schema receive special type handling at any nesting depth (including inside array `items`). These are unrelated to the top-level `start_time` / `end_time` request parameters. The platform returns the value in a format determined by the declared type: *Allowed declarations:* | Declared type | Platform behavior | |---------------|-------------------| | `number` | Passes the value through without conversion. | | `integer` | Rounds the value to the nearest integer. | | `string` (no `format`) | Converts the value to the `hh:mm:ss.fff` format. | | `timestamp` with `format` | See the **Timestamp type** section above for the available formats. | *Rejected declarations (returns `400` error):* - `string` with any `format` keyword (`time`, `date-time`, `email`, `uri`, etc.) - `boolean` - `object` - `array` - `null` All other property names in your schema remain unconstrained by these rules. For other field names, use the `timestamp` type described above. **Response validation** Check the `FinishReason` field to verify your JSON response is complete: - When `FinishReason` is `stop`, the generation completed normally, and the JSON is valid and complete. - When `FinishReason` is `length`, the platform truncates the response at the maximum response length or the context window. This may result in truncated, invalid JSON that fails to parse.
  - `max_tokens` integer — The maximum response length, in tokens. The allowed range depends on the model: | Model | Min | Max | Default | |-------|-----|-----|---------| | Pegasus 1.2 | 2 | 4,096 | 4,096 | | Pegasus 1.5 | 512 | 98,304 | 4,096 |
  - `start_time` number, double — Start of the analysis window, as an absolute timestamp in seconds, based on the video's internal metadata. Use with `end_time` to analyze only a portion of the video. Requires `model_name` set to `pegasus1.5`. <Note title="Notes"> - If omitted, defaults to the video's internal start time. - 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 less than the video duration. The clip (`end_time - start_time`) must be at least `4` seconds. </Note>
  - `end_time` number, double — End of the analysis window, as an absolute timestamp in seconds, based on the video's internal metadata. Use with `start_time` to analyze only a portion of the video. Requires `model_name` set to `pegasus1.5`. <Note title="Notes"> - If omitted, defaults to the video's internal start time 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 clip (`end_time - start_time`) must be at least `4` seconds. </Note>

## Response `200`

The specified video has successfully been analyzed.

- union
  - union — When the value of the `stream` parameter is set to `true`, the platform provides a streaming response in the NDJSON format. The stream contains three types of events: 1. Stream start 2. Text generation 3. Stream end To integrate the response into your application, follow the guidelines below: - Parse each line of the response as a separate JSON object. - Check the `event_type` field to determine how to handle the event. - For `text_generation` events, process the `text` field as it arrives. Depending on your application's requirements, this may involve displaying the text incrementally, storing it for later use, or performing any tasks. - Use the `stream_start` and `stream_end` events to manage the lifecycle of your streaming session.
    - object — Indicates the beginning of the stream.
      - `event_type` 'stream_start', required — This field is always set to `stream_start` for this event.
      - `metadata` StreamStartResponseMetadata — An object containing metadata about the stream.
        - `generation_id` string — A unique identifier for the generation session.
    - object — Contains a fragment of generated text. Note that text fragments may be split at arbitrary points, not necessarily at word or sentence boundaries.
      - `event_type` 'text_generation', required — This field is always set to `text_generation` for this event.
      - `text` string — A fragment of the generated text.
    - object — Indicates the end of the stream.
      - `event_type` 'stream_end', required — This field is always set to `stream_end` for this event.
      - `finish_reason` 'stop' | 'length' — The reason the generation stopped. - `stop`: The generation reached the end of the output text. - `length`: The response reached the maximum response length or the context window. For JSON responses, this may return truncated JSON that fails to parse.
      - `metadata` StreamEndResponseMetadata — An object containing metadata about the stream.
        - `generation_id` string — The same unique identifier provided in the `stream_start` event.
        - `usage` TokenUsage — The number of tokens used in the generation.
          - `output_tokens` integer, required — The number of tokens in the generated text.
          - `input_tokens` integer — 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#context-window).
      - `error` AnalyzeTaskError — A message attached to an analysis response. The platform uses this object in three cases: - **Task failure** — set on `AnalyzeTaskResponse.error` when `status` is `failed`. The `message` field describes the failure. - **Truncation: maximum response length reached** — set on the response `error` when `finish_reason` is `length` because `output_tokens` reached the requested `max_tokens` value. The `message` field advises increasing the `max_tokens` value. - **Truncation: context window reached** — set on the response `error` when `finish_reason` is `length` because the input and response reached the [context window](/v1.3/docs/concepts/models/pegasus#context-window). The `message` field advises reducing the input size or decreasing the `max_tokens` value. For truncation cases, the partial output is in `result.data` (async) or `data` (sync). Check `finish_reason` instead of parsing the message text.
        - `message` string, required — A human-readable message. One of: - **Failure** (async, `status: failed`): describes the failure reason, e.g., `"Video duration exceeds maximum allowed duration"`. - **Truncation: maximum response length reached** (`finish_reason: length`, `output_tokens >= max_tokens`): `"output truncated: the generation reached the configured max_tokens. The partial output is returned; raise max_tokens (up to 98304) if you need a longer response."`. - **Truncation: context window reached** (`finish_reason: length`, model stopped before reaching `max_tokens`): `"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 exact text is not part of the contract — SDKs should not parse it.
  - NonStreamAnalyzeResponse — When the value of the `stream` parameter is set to `false`, the response is as follows:
    - `id` string — Unique identifier of the response.
    - `data` string — The generated text based on the prompt you provided.
    - `finish_reason` 'stop' | 'length' — The reason the generation stopped. - `stop`: The generation reached the end of the output text. - `length`: The response reached the maximum response length or the context window. For JSON responses, this may return truncated JSON that fails to parse.
    - `usage` TokenUsage — The number of tokens used in the generation.
      - `output_tokens` integer, required — The number of tokens in the generated text.
      - `input_tokens` integer — 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#context-window).
    - `error` AnalyzeTaskError — A message attached to an analysis response. The platform uses this object in three cases: - **Task failure** — set on `AnalyzeTaskResponse.error` when `status` is `failed`. The `message` field describes the failure. - **Truncation: maximum response length reached** — set on the response `error` when `finish_reason` is `length` because `output_tokens` reached the requested `max_tokens` value. The `message` field advises increasing the `max_tokens` value. - **Truncation: context window reached** — set on the response `error` when `finish_reason` is `length` because the input and response reached the [context window](/v1.3/docs/concepts/models/pegasus#context-window). The `message` field advises reducing the input size or decreasing the `max_tokens` value. For truncation cases, the partial output is in `result.data` (async) or `data` (sync). Check `finish_reason` instead of parsing the message text.
      - `message` string, required — A human-readable message. One of: - **Failure** (async, `status: failed`): describes the failure reason, e.g., `"Video duration exceeds maximum allowed duration"`. - **Truncation: maximum response length reached** (`finish_reason: length`, `output_tokens >= max_tokens`): `"output truncated: the generation reached the configured max_tokens. The partial output is returned; raise max_tokens (up to 98304) if you need a longer response."`. - **Truncation: context window reached** (`finish_reason: length`, model stopped before reaching `max_tokens`): `"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 exact text is not part of the contract — SDKs should not parse it.

## Other responses

- `400` — The request has failed.
- `404` — The specified resource does not exist.
- `429` — If the rate limit is reached, the platform returns an `HTTP 429 - Too many requests` error response. The response body is empty.

---

[API](https://skmtc.net/twelvelabs/apis/twelvelabs-api.md) · [All operations](https://skmtc.net/twelvelabs/apis/twelvelabs-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/twelvelabs/twelvelabs-api/revisions/b6d766c2c340/schema)