> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.twelvelabs.io/v1.3/api-reference/upload-files/direct-uploads/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.twelvelabs.io/_mcp/server.

# Direct uploads

> Upload media and documents directly to the platform. Processing is asynchronous; poll the asset status until it is ready.

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`](/v1.3/api-reference/upload-content/direct-uploads/create) method of the `/assets` endpoint. You receive the identifier of the asset in the response.

Asset processing is asynchronous. Poll the [`GET`](/v1.3/api-reference/upload-content/direct-uploads/retrieve) 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](/v1.3/api-reference/create-embeddings-v2).
* **For entity search** (images): Use the identifier of the asset to [create entities](/v1.3/api-reference/entities/entity-collections/entities/create).
* **For search and analysis** (videos): [Index your asset](/api-reference/index-content/create) using the asset ID.

# Supported content

Direct uploads support:

* Video, audio, and images.
* 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.

The platform generates thumbnail images from the uploaded content by default. Set the `enable_thumbnail` parameter to `false` to disable thumbnail generation. PDF thumbnails represent the first page. Text and Markdown files do not produce thumbnails. The platform generates an HLS playlist and segments for video and audio assets by default. Set the `enable_hls` parameter to `false` to disable HLS generation.

> Upload media and documents directly to the platform. Processing is asynchronous; poll the asset status until it is ready.


## API Docs

- Direct uploads [Create an asset](https://docs.twelvelabs.io/api-reference/upload-files/direct-uploads/create.md)

## OpenAPI Specification

The raw OpenAPI 3.1 specification for this API is available at:
- [OpenAPI JSON](https://docs.twelvelabs.io/v1.3/api-reference/upload-files/direct-uploads/openapi.json)
- [OpenAPI YAML](https://docs.twelvelabs.io/v1.3/api-reference/upload-files/direct-uploads/openapi.yaml)