For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
This method creates an asset by uploading a file to the platform. Assets are media files that you can use in downstream workflows, including indexing, analyzing video content, and creating entities.
**Supported content**: Video, audio, and images.
**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 5 MB
**Additional requirements** depend on your workflow:
- **Search**: [Marengo requirements](/v1.3/docs/concepts/models/marengo#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#image-file-requirements)
- **Create embeddings**: [Marengo requirements](/v1.3/docs/concepts/models/marengo#input-requirements)
<Note title="Note">
This endpoint is rate-limited. For details, see the [Rate limits](/v1.3/docs/get-started/rate-limits) page.
</Note>
This method creates an asset by uploading a file to the platform. Assets are media files that you can use in downstream workflows, including indexing, analyzing video content, and creating entities.
Supported content: Video, audio, and images.
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.
This endpoint is rate-limited. For details, see the Rate limits page.
Authentication
x-api-keystring
Your API key.
<Note title="Note">
You can find your API key on the <a href="https://playground.twelvelabs.io/dashboard/api-keys" target="_blank">API Keys</a> page.
</Note>
Request
This endpoint expects a multipart form containing an optional file.
methodenumRequired
Specifies the upload method for the asset. Use direct to upload a local file or url for a publicly accessible URL.
Allowed values:
filefileOptional
Specify this parameter to upload a file from your local file system. This parameter is required when method is set to direct.
Local video and audio files support up to 200 MB. Image files support up to 5 MB.
urlstringOptional
Specify this parameter to upload a file from a publicly accessible URL. 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 5 MB.
filenamestringOptional1-255 characters
The optional filename of the asset. If not provided, the platform will determine the filename from the file or URL.
enable_hlsbooleanOptionalDefaults to false
When set to true, the platform generates an HLS playlist and segments for streaming. Applicable to video and audio assets only.
Default: false.
enable_thumbnailbooleanOptionalDefaults to false
When set to true, the platform generates thumbnail images from the uploaded content.
Default: false.
user_metadatastringOptional
Metadata that helps you categorize your assets. You can specify a list of keys and values. Keys must be of type string, and values can be of the following types: string, integer, float, or boolean. Send this value as a JSON-encoded string.
Response
The asset has been successfully created.
_idstring
The unique identifier of the asset.
methodenum
Indicates how you uploaded the asset.
Values:
direct: Uploaded from your local file system
url: Uploaded from a publicly accessible URL
multipart: Uploaded using the multipart upload flow
Allowed values:
statusenum
Indicates the current status of the asset.
Values:
failed: The platform failed to process the upload
processing: The platform is processing the uploaded file
ready: The asset is ready to use
Allowed values:
filenamestring
The name of the file used to create the asset.
file_typestring
The MIME type of the asset file.
sizeinteger
The file size of the asset in bytes. This field is absent while the asset is still being processed.
durationdouble
The duration of the asset in seconds. Only present for video and audio assets. This field is absent for image assets or while the asset is still being processed.
created_atstringformat: "date-time"
The date and time, in RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the asset was created.
user_metadatamap from strings to any
User-defined metadata for this asset. This field is absent when no metadata has been set.
