Create a video embedding task

This method creates a new video embedding task that uploads a video to the platform and creates one or multiple video embeddings.

Upload options:

Local file: Use the video_file parameter
Publicly accessible URL: Use the video_url parameter.

Specify at least one option. If both are provided, video_url takes precedence.

Video requirements

The videos you wish to upload must meet the following requirements:

Video resolution: Must be at least 360x360 and must not exceed 3840x2160.
Aspect ratio: Must be one of 1:1, 4:3, 4:5, 5:4, 16:9, 9:16, or 17:9.
Video and audio formats: Your video files must be encoded in the video and audio formats listed on the FFmpeg Formats Documentation page. For videos in other formats, contact us at support@twelvelabs.io.
Duration: Must be between 4 seconds and 2 hours (7,200s).
File size: Must not exceed 2 GB. If you require different options, contact us at support@twelvelabs.io.
Video URLs: Must be direct links to raw video files that play without user interaction or custom video players (example: https://example.com/videos/sample-video.mp4). Video hosting platforms like YouTube and cloud storage sharing links are not supported.

Notes

The Marengo video understanding model generates embeddings for all modalities in the same latent space. This shared space enables any-to-any searches across different types of content.
Video embeddings are stored for seven days.

This method creates a new video embedding task that uploads a video to the platform and creates one or multiple video embeddings. Upload options: - **Local file**: Use the `video_file` parameter - **Publicly accessible URL**: Use the `video_url` parameter. Specify at least one option. If both are provided, `video_url` takes precedence. <Accordion title="Video requirements"> The videos you wish to upload must meet the following requirements: - **Video resolution**: Must be at least 360x360 and must not exceed 3840x2160. - **Aspect ratio**: Must be one of 1:1, 4:3, 4:5, 5:4, 16:9, 9:16, or 17:9. - **Video and audio formats**: Your video files must be encoded in the video and audio formats listed on the [FFmpeg Formats Documentation](https://ffmpeg.org/ffmpeg-formats.html) page. For videos in other formats, contact us at support@twelvelabs.io. - **Duration**: Must be between 4 seconds and 2 hours (7,200s). - **File size**: Must not exceed 2 GB. If you require different options, contact us at support@twelvelabs.io. - **Video URLs**: Must be direct links to raw video files that play without user interaction or custom video players (example: `https://example.com/videos/sample-video.mp4`). Video hosting platforms like YouTube and cloud storage sharing links are not supported. </Accordion> <Note title="Notes"> - The Marengo video understanding model generates embeddings for all modalities in the same latent space. This shared space enables any-to-any searches across different types of content. - Video embeddings are stored for seven days. </Note>

Authentication

x-api-keystring

Your API key.

Note

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

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

Request

Request to create a video embedding task.

model_namestringRequired

The name of the model you want to use. The following models are available:

Marengo-retrieval-2.7

The name of the model you want to use. The following models are available: - `Marengo-retrieval-2.7`

video_filefileOptional

Specify this parameter to upload a video from your local file system.

video_urlstringOptional

Specify this parameter to upload a video from a publicly accessible URL.

video_start_offset_secdoubleOptional

The start offset in seconds from the beginning of the video where processing should begin. Specifying 0 means starting from the beginning of the video.

Default: 0 Min: 0 Max: Duration of the video minus video_clip_length

video_end_offset_secdoubleOptional

The end offset in seconds from the beginning of the video where processing should stop.

Ensure the following when you specify this parameter:

The end offset does not exceed the total duration of the video file.
The end offset is greater than the start offset.
You must set both the start and end offsets. Setting only one of these offsets is not permitted, resulting in an error.

Min: video_start_offset + video_clip_length Max: Duration of the video file

The end offset in seconds from the beginning of the video where processing should stop. Ensure the following when you specify this parameter: - The end offset does not exceed the total duration of the video file. - The end offset is greater than the start offset. - You must set both the start and end offsets. Setting only one of these offsets is not permitted, resulting in an error. **Min**: video_start_offset + video_clip_length **Max**: Duration of the video file

video_clip_lengthdoubleOptional

The desired duration in seconds for each clip for which the platform generates an embedding. Ensure that the clip length does not exceed the interval between the start and end offsets.

Default: 6 Min: 2 Max: 10

video_embedding_scopelist of enumsOptional

Defines the scope of video embedding generation. Valid values are the following:

clip: Creates embeddings for each video segment of video_clip_length seconds, from video_start_offset_sec to video_end_offset_sec.
clip and video: Creates embeddings for video segments and the entire video.

To create embeddings for segments and the entire video in the same request, include this parameter twice as shown below:

1 --form video_embedding_scope=clip \
2 --form video_embedding_scope=video

Default: clip

Defines the scope of video embedding generation. Valid values are the following: - `clip`: Creates embeddings for each video segment of `video_clip_length` seconds, from `video_start_offset_sec` to `video_end_offset_sec`. - `clip` and `video`: Creates embeddings for video segments and the entire video. To create embeddings for segments and the entire video in the same request, include this parameter twice as shown below: ```json --form video_embedding_scope=clip \ --form video_embedding_scope=video ``` **Default**: `clip`

Allowed values:

Response

A video embedding task has successfully been created.

_idstring or null

The unique identifier of the video embedding task. You can use the identifier to:

Retrieve the status of your task by invoking the GET method of the /embed/tasks/{task_id}/status endpoint.
Retrieve the embedding by invoking the GET method of the /embed/tasks/{task_id} endpoint.

The unique identifier of the video embedding task. You can use the identifier to: - Retrieve the status of your task by invoking the [`GET`](/v1.3/api-reference/video-embeddings/retrieve-video-embedding-task-status) method of the `/embed/tasks/{task_id}/status` endpoint. - Retrieve the embedding by invoking the [`GET`](/v1.3/api-reference/video-embeddings/retrieve-video-embeddings) method of the `/embed/tasks/{task_id}` endpoint.

Errors