> This page is for version v1.3 (default). > For other versions, use one of these documentation indexes: > - v1.3 (default): https://docs.twelvelabs.io/v1.3/llms.txt > 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 `Assets` 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/node-js/upload-files/direct-uploads#create-an-asset) method. You receive the identifier of the asset in the response. Asset processing is asynchronous. Poll the [`assets.retrieve`](/v1.3/sdk-reference/node-js/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 identifier of the asset with the [Embed API v2](/v1.3/sdk-reference/node-js/create-embeddings-v-2). * **For entity search (images)**: Use the identifier of the asset to [create entities](/v1.3/sdk-reference/node-js/manage-entities#create-an-entity). * **For search and analysis (videos)**: [Index your asset](/v1.3/sdk-reference/node-js/index-content#index-an-asset) using the identifier of the asset. # 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/node-js/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/pegasus-1-6#input-requirements) * **Image analysis**: [Pegasus image requirements](/v1.3/docs/concepts/models/pegasus/pegasus-1-6#image-file-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`** ```javascript Function signature create( request: TwelvelabsApi.AssetsCreateRequest, requestOptions?: Assets.RequestOptions ): core.HttpResponsePromise ``` **`Node.js example`** ```javascript Node.js example import { TwelveLabs } from "twelvelabs-js"; const asset = await client.assets.create({ method: "url", url: "", filename: "" }); console.log(`Asset ID: ${asset.id}`); console.log(`Status: ${asset.status}`); console.log(`Filename: ${asset.filename}`); ``` ### Parameters | Name | Type | Required | Description | | :--------------- | :---------------------------------- | :------- | :-------------------------------- | | `request` | `TwelvelabsApi.AssetsCreateRequest` | Yes | Parameters for creating an asset. | | `requestOptions` | `Assets.RequestOptions` | No | Request-specific configuration. | The `TwelvelabsApi.AssetsCreateRequest` interface has the following properties: | Name | Type | Required | Description | | ----------------- | -------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `method` | `TwelvelabsApi.AssetsCreateRequestMethod` | Yes | Specifies the upload method for the asset. Use `direct` to upload a local file or `url` for a publicly accessible URL. | | `file` | `File \| fs.ReadStream \| Blob \| undefined` | 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` | `string` | 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` | `string` | 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. | | `enableHls` | `boolean` | 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`. | | `enableThumbnail` | `boolean` | 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`. | | `userMetadata` | `string` | 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. | ### Return value Returns an `HttpResponsePromise` that resolves to a `TwelvelabsApi.Asset` object representing the created asset. The `TwelvelabsApi.Asset` interface contains the following properties: | Name | Type | Description | | -------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | `string` | The unique identifier of the asset. | | `method` | `TwelvelabsApi.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` | `TwelvelabsApi.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` | `string` | The name of the file used to create the asset. | | `fileType` | `string` | The MIME type of the asset file. For documents, this is `application/pdf`, `text/plain`, or `text/markdown`. | | `createdAt` | `Date` | The date and time, in RFC 3339 format ("YYYY-MM-DDTHH:mm:ssZ"), when the asset was created. | | `userMetadata` | `TwelvelabsApi.UserMetadata` | User-defined metadata for this asset. This field is absent when no metadata has been set. | | `source` | `TwelvelabsApi.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)