API ReferenceAnalyze videos

Create an async analysis task

This method asynchronously analyzes your videos and generates fully customizable text based on your prompts. <Accordion title="Input requirements"> - Minimum duration: 4 seconds - Maximum duration: 2 hours - 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 longer than 1 hour - Process videos asynchronously without blocking your application **Do not use this method for**: - Videos for which you need immediate results or real-time streaming. Use the [`POST`](/v1.3/api-reference/analyze-videos/sync-analysis) method of the `/analyze` endpoint instead. Analyzing videos asynchronously requires three steps: 1. Create an analysis task using this method. The platform returns a task ID. 2. Poll the status of the task using the [`GET`](/v1.3/api-reference/analyze-videos/retrieve-analysis-task-status-results) method of the `/analyze/tasks/{task_id}` endpoint. Wait until the status is `ready`. 3. Retrieve the results from the response when the status is `ready` using the [`GET`](/v1.3/api-reference/analyze-videos/retrieve-analysis-task-status-results) method of the `/analyze/tasks/{task_id}` endpoint. <Note title="Note"> This endpoint is rate-limited. For details, see the [Rate limits](/v1.3/docs/get-started/rate-limits) page. </Note>

Authentication

x-api-keystring
Your API key. <Note title="Note"> You can find your API key on the <a href="https://playground.twelvelabs.io/dashboard/api-keys" target="_blank">API Keys</a> page. </Note>

Request

This endpoint expects an object.
videoobjectRequired
An object specifying the source of the video content. Include exactly one source.
promptstringRequired
A prompt that guides the model on the desired format or content. <Note title="Notes"> - Even though the model behind this endpoint is trained to a high degree of accuracy, the preciseness of the generated text may vary based on the nature and quality of the video and the clarity of the prompt. - Your prompts can be instructive or descriptive, or you can also phrase them as questions. - The maximum length of a prompt is 2,000 tokens. </Note> **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.
temperaturedoubleOptional

Controls the randomness of the text output.

Default: 0.2 Min: 0 Max: 1

max_tokensintegerOptional1-4096

The maximum number of tokens to generate.

Min: 1 Max: 4096

response_formatobjectOptional
Specifies the format of the response. When you omit this parameter, the platform returns unstructured text.

Response

An analysis task has successfully been created.
task_idstring
The unique identifier of the analysis task.
statusenum
The current status of the analysis task.
Allowed values:

Errors

400
Bad Request Error
500
Internal Server Error