Create a video indexing task

This method will be removed in a future version. New implementations should use direct or multipart uploads followed by separate indexing.

This method creates a video indexing task that uploads and indexes a video in a single operation.

Adding videos to existing indexes

You can no longer add videos to an index that has only Pegasus 1.2 enabled. When you add videos to an index that has both Marengo and Pegasus 1.2 enabled, the platform indexes them with Marengo only.

Upload options:

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

Your videos must meet requirements based on your workflow:

Search: Marengo requirements.
Video analysis: Pegasus requirements.
If you want to both search and analyze your videos, the most restrictive requirements apply.
This method allows you to upload files up to 2 GB in size. To upload larger files, use the Multipart Upload API

Indexes have limits on video hours and video count. 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

Request to upload a video to an index.

index_idstringRequired

The unique identifier of the index to which the video is being uploaded.

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.

enable_video_streambooleanOptionalDefaults to true

This parameter indicates if the platform stores the video for streaming. When set to true, the platform stores the video, and you can retrieve its URL by calling the GET method of the /indexes/{index-id}/videos/{video-id} endpoint. You can then use this URL to access the stream over the HLS protocol.

user_metadatastringOptional

Metadata that helps you categorize your videos. You can specify a list of keys and values. Keys are strings, and values can be a string, a number, a boolean, or an array of strings. Send an integer wider than 53 bits (-9007199254740991 to 9007199254740991), and any identifier you want preserved verbatim, as a string. Send this value as a JSON-encoded string.

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 indexing task has successfully been created.

_idstringOptional

A string representing the unique identifier of your video indexing task.

video_idstringOptional

A string representing the unique identifier of the video associated with the specified video indexing task.

Errors

400

Bad Request Error

422

Unprocessable Entity Error

429

Too Many Requests Error