Upload videos, images, audio, and documents to the TwelveLabs platform. This method creates an asset that you can use in different workflows.

Workflow

Upload your file using the POST method of the /assets endpoint. You receive the identifier of the asset in the response.

Asset processing is asynchronous. Poll the GET method of the /assets/{asset-id} endpoint until the status field is ready before proceeding.

What you do next depends on your use case:

For creating embeddings (videos, audio, images): Use the identifier of the asset with the Embed API v2.
For entity search (images): Use the identifier of the asset to create entities.
For search and analysis (videos): Index your asset using the asset ID.

Supported content

Direct uploads support:

Video, audio, and image files.
PDF, text, and Markdown files.

Limits and processing

Local video, audio, and documents: Up to 200 MB.
Public video and audio URLs: Up to 4 GB.
Images: Up to 32 MB.
Public document URLs: Up to 512 MB.

The platform processes every upload asynchronously. The asset starts in the processing status and transitions to ready when it is usable or failed when the file cannot be validated or processed. Failed assets include an error object with a client-safe message.

Validation and thumbnails

Filename extension matching is case-insensitive, and the original filename is preserved. The platform rejects unsupported formats. For documents, it also rejects files whose extensions don’t match the detected content.

Set the enable_thumbnail parameter to true to request thumbnail generation. PDF thumbnails represent the first page. Text and Markdown files do not produce thumbnails. Use the enable_hls parameter for video and audio assets.