Skip to navigation
Models and searchCreate embeddings v1Create video embeddings

Create a video embedding task

Note

This endpoint will be deprecated in a future version. Migrate to the Embed API v2 for continued support and access to new features.

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

Note

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

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.

Your videos must meet the requirements. This endpoint allows you to upload files up to 2 GB in size. To upload larger files, use the Multipart Upload API

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.

Authentication

x-api-keystring

Your API key.

Note

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

Request

Request to create a video embedding task.
model_namestringRequired

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

  • marengo3.0: Enhanced model with sports intelligence and extended content support.
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

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. Use the video scope for videos up to 10-30 seconds to maintain optimal performance.

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

--form video_embedding_scope=clip \
--form video_embedding_scope=video

Default: clip

Allowed values:

Response headers

X-Ratelimit-DimensionsstringOptional

A comma-separated, alphabetically sorted list of the rate limits the request was measured against. Only the limits that applied to the request appear.

Each entry is a label. Replace <label> with an entry to read the values for that limit: X-Ratelimit-<label>-Limit, X-Ratelimit-<label>-Remaining, and X-Ratelimit-<label>-Reset. This list keeps the mixed-case spelling of each label, such as InputToken-Video. The platform sends the headers as X-Ratelimit-Inputtoken-Video-Limit. HTTP header names are case-insensitive, so the two spellings match.

Some accounts receive the legacy X-Ratelimit-Limit, X-Ratelimit-Remaining, X-Ratelimit-Used, and X-Ratelimit-Reset headers instead of this family. A response does not include both families. The /embed-v2, /embed-v2/tasks, and /knowledge-stores/{knowledge_store_id}/search endpoints send only this family. For details, see Legacy headers.

X-Ratelimit-Request-Limitinteger

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

X-Ratelimit-Request-Remaininginteger
The number of requests remaining in the current rate limit window for this endpoint.
X-Ratelimit-Request-Resetinteger
The time at which the current request rate limit window resets, expressed in UTC epoch seconds.
X-Ratelimit-Duration-Limitinteger

The maximum duration of video and audio, in seconds, that you can process per rate limit window for this endpoint. For details, see the Rate limits page.

X-Ratelimit-Duration-Remaininginteger
The duration of video and audio, in seconds, that you can still process in the current rate limit window for this endpoint.
X-Ratelimit-Duration-Resetinteger
The time at which the current duration rate limit window resets, expressed in UTC epoch seconds.
X-Ratelimit-Limitdouble

The maximum number of requests you can make per rate limit window for this endpoint. Some accounts receive this legacy header instead of the X-Ratelimit-Dimensions family. For details, see Legacy headers.

X-Ratelimit-Remainingdouble

The number of requests remaining in the current rate limit window for the specific endpoint. Some accounts receive this legacy header instead of the X-Ratelimit-Dimensions family. For details, see Legacy headers.

X-Ratelimit-Useddouble

The number of requests you have made in the current rate limit window for the specific endpoint. Some accounts receive this legacy header instead of the X-Ratelimit-Dimensions family. For details, see Legacy headers.

X-Ratelimit-Resetdouble

The time at which the current rate limit window resets, expressed in UTC epoch seconds. Some accounts receive this legacy header instead of the X-Ratelimit-Dimensions family. For details, see Legacy headers.

Response

A video embedding task has successfully been created.
_idstringOptional

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.

Errors

400
Bad Request Error
422
Unprocessable Entity Error
429
Too Many Requests Error