> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.twelvelabs.io/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 files directly to the platform. Processing is asynchronous; poll the asset status until it is ready. The `AssetsClient` class provides methods to upload your media and documents to the platform. This method creates an asset that you can use in different workflows. # Workflow Upload your file using the [`assets.create`](/v1.3/sdk-reference/python/upload-files/direct-uploads#create-an-asset) method. You receive the asset ID in the response. Asset processing is asynchronous. Poll the [`assets.retrieve`](/v1.3/sdk-reference/python/manage-assets#retrieve-an-asset) method 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 asset ID with the [Embed API v2](/v1.3/sdk-reference/python/create-embeddings-v-2). * **For entity search (images)**: Use the asset ID to [create entities](/v1.3/sdk-reference/python/manage-entities#create-an-entity). * **For search and analysis (videos)**: [Index your asset](/v1.3/sdk-reference/python/index-content#index-an-asset) using the asset ID. # Methods ## Create an asset **Description**: This method creates an asset by uploading a file to the platform. Assets are reusable files that you can use in different workflows. The platform processes uploads asynchronously. This method returns immediately with the asset in the `processing` status, which then transitions to the `ready` status on success or to the `failed` status when the file is invalid, corrupt, or unreadable, typically within a few seconds to a few minutes. Poll the [`assets.retrieve`](/v1.3/sdk-reference/python/manage-assets#retrieve-an-asset) method until the `status` field is `ready` before you use the asset. This applies to every upload, including small files. **Supported content**: * Video, audio, and images. * PDF, text, and Markdown files. Filename extension matching is case-insensitive; for example, `notes.MD` and `notes.md` are treated the same. The platform rejects unsupported formats. For documents, it also rejects files whose extensions don't match the detected content. **Upload methods**: * **Local file**: Set the `method` parameter to `direct` and use the `file` parameter to specify the file. * **Publicly accessible URL**: Set the `method` parameter to `url` and use the `url` parameter to specify the URL of your file. **Upload limits**: * Video and audio, local files: Up to 200 MB * Video and audio, public URLs: Up to 4 GB * Images: Up to 32 MB * Documents, local files: Up to 200 MB * Documents, public URLs: Up to 512 MB Asset creation does not enforce a maximum duration for video and audio files. Each model applies its own file size and duration limits. For details, see the requirements below. **Additional requirements** depend on your workflow: * **Search**: [Marengo requirements](/v1.3/docs/concepts/models/marengo/marengo-3-0#video-file-requirements) * **Video analysis**: [Pegasus requirements](/v1.3/docs/concepts/models/pegasus#input-requirements) * **Entity search**: [Marengo image requirements](/v1.3/docs/concepts/models/marengo/marengo-3-0#image-file-requirements) * **Create embeddings**: [Marengo requirements](/v1.3/docs/concepts/models/marengo/marengo-3-5#input-requirements) > **Note** > > This method is rate-limited. For details, see the [Rate limits](/v1.3/docs/get-started/rate-limits) page. **Function signature and example**: **`Function signature`** ```python Function signature def create( self, *, method: AssetsCreateRequestMethod, file: typing.Optional[core.File] = OMIT, url: typing.Optional[str] = OMIT, filename: typing.Optional[str] = OMIT, enable_hls: typing.Optional[bool] = OMIT, enable_thumbnail: typing.Optional[bool] = OMIT, user_metadata: typing.Optional[str] = OMIT, request_options: typing.Optional[RequestOptions] = None, ) -> Asset ``` **`Python example`** ```python Python example from twelvelabs import TwelveLabs asset = client.assets.create( method="url", url="", filename="" ) print(f"Asset ID: {asset.id}") print(f"Status: {asset.status}") print(f"Filename: {asset.filename}") ``` ### Parameters | Name | Type | Required | Description | | ------------------ | --------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `method` | `AssetsCreateRequestMethod` | Yes | Specifies the upload method for the asset. Use `direct` to upload a local file or `url` for a publicly accessible URL. | | `file` | `core.File` | No | The local file to upload. This parameter is required when `method` is set to `direct`. Local video, audio, and documents support up to 200 MB. Images support up to 32 MB. | | `url` | `str` | No | The publicly accessible URL of a media file or document to upload. This parameter is required when `method` is set to `url`. Public video and audio URLs support up to 4 GB. Image URLs support up to 32 MB. Document URLs support up to 512 MB. The parameter also accepts the URL of an HLS manifest (`.m3u8`) in VOD format. Live video streams are rejected with a `400` error. If the duration cannot be determined from the media, the platform calculates it from the manifest. | | `filename` | `str` | No | The filename of the asset. If you provide a filename, the platform preserves it. If you omit it, the platform determines one from the file or URL. | | `enable_hls` | `bool` | No | The platform generates an HLS playlist and segments for streaming. Set to `false` to disable HLS generation. Applicable to video and audio assets only. The platform ignores this flag for other asset types. Default: `true`. | | `enable_thumbnail` | `bool` | No | The platform generates thumbnail images from the uploaded content. Set to `false` to disable thumbnail generation. For PDF files, the representative thumbnail uses the first page. Text and Markdown files do not produce thumbnails; the platform ignores this flag for them. Default: `true`. | | `user_metadata` | `str` | No | Metadata that helps you categorize your assets. 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 this value as a JSON-encoded string. | | `request_options` | `RequestOptions` | No | Request-specific configuration. | ### Return value Returns an object of type `Asset` representing the created asset. The `Asset` class contains the following properties: | Name | Type | Description | | --------------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | `Optional[str]` | The unique identifier of the asset. | | `method` | `Optional[AssetMethod]` | Indicates how the asset was uploaded or imported. Values: `direct` (uploaded from your local file system), `url` (uploaded from a publicly accessible URL), `multipart` (uploaded using the multipart upload flow), `connector` (imported through a data connector). | | `status` | `Optional[AssetStatus]` | Indicates the current processing status of the asset. Values: `processing` (the asset is not yet usable; the upload is still in progress, or the platform is validating the file), `ready` (the platform validated the asset successfully and it is ready to use), `failed` (the platform could not process the file; the `error` field describes the reason). | | `filename` | `Optional[str]` | The name of the file used to create the asset. | | `file_type` | `Optional[str]` | The MIME type of the asset file. For documents, this is `application/pdf`, `text/plain`, or `text/markdown`. | | `created_at` | `Optional[datetime]` | The date and time, in RFC 3339 format ("YYYY-MM-DDTHH:mm:ssZ"), when the asset was created. | | `user_metadata` | `Optional[Dict[str, Optional[UserMetadataValue]]]` | User-defined metadata for this asset. This field is absent when no metadata has been set. | | `source` | `Optional[AssetSource]` | Describes where the asset came from. Present only for assets imported through a connector; absent for assets uploaded directly to the `/assets` endpoint. | ### API Reference [Create an asset](/v1.3/api-reference/upload-content/direct-uploads/create)