Skip to navigation
Models and searchAnalyze and segment videos

Sync analysis

This method analyzes your videos and returns the results directly in the response. It supports general analysis (prompt-based text generation).

  • Minimum duration: 1 second
  • Maximum duration: 1 hour
  • Formats: FFmpeg supported formats
  • Resolution: 360x360 to 5184x2160 pixels
  • Aspect ratio: Between 1:1 and 1:2.4, or between 2.4:1 and 1:1.

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 method of the /analyze/tasks endpoint instead.
  • Video segmentation with custom segment definitions. Use the POST method of the /analyze/tasks endpoint 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 section.

Note

This endpoint is rate-limited. For details, see the Rate limits page.

Authentication

x-api-keystring

Your API key.

Note

You can find your API key on the API Keys page.

Request

Defines the synchronous analysis request.
model_nameenumOptionalDefaults to pegasus1.5

The video understanding model to use for analysis.

  • pegasus1.5: General analysis (prompt-based text generation) with video clipping, structured prompts with reference images, and video segmentation (async only). See the Pegasus page for token limits.

Default: pegasus1.5

Allowed values:
videoobjectOptional
An object specifying the source of the video content. Include exactly one source.
promptstringOptional

A text prompt that guides the model on the desired format or content. To include reference images in your prompt, use the prompt_v2 parameter instead. Mutually exclusive with the prompt_v2 parameter.

Your prompts can be instructive or descriptive, or you can phrase them as questions. This text counts toward the context window.

prompt_v2objectOptional

A structured prompt with <@name> placeholders for referencing images. Mutually exclusive with the prompt parameter.

The prompt text and reference images count toward the context window.

temperaturedoubleOptional

Controls the randomness of the text output.

Default: 0.2 Min: 0 Max: 1

streambooleanOptionalDefaults to true

Set this parameter to true to enable streaming responses in the NDJSON format.

Default: true

response_formatobjectOptional

Specifies the format of the response. When you omit this parameter, the platform returns unstructured text. Only the json_schema type is supported for synchronous analysis.

max_tokensintegerOptional512-98304Defaults to 4096
The maximum response length, in tokens.
start_timedoubleOptional

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.

Notes
  • 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_timedoubleOptional

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.

Notes
  • 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.

Response headers

X-Ratelimit-Limitdouble

The maximum number of requests you can make per rate limit window for this endpoint. For details, see the Rate limits page.

X-Ratelimit-Remainingdouble
The number of requests remaining in the current rate limit window for the specific endpoint.
X-Ratelimit-Useddouble
The number of requests you have made in the current rate limit window for the specific endpoint.
X-Ratelimit-Resetdouble
The time at which the current rate limit window resets, expressed in UTC epoch seconds.
Transfer-EncodingstringOptional

Response

The specified video has successfully been analyzed.
Streamed responseobject

When the value of the stream parameter is set to true, the platform provides a streaming response in the NDJSON format.

The stream contains the following types of events:

  • Stream start
  • Text generation
  • 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.
OR
Non-streamed responseobject

When the value of the stream parameter is set to false, the response is as follows:

Errors

400
Bad Request Error
404
Not Found Error
429
Too Many Requests Error