AssetsManage assets

Retrieve an asset

This method retrieves details about the specified asset.

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>

Path parameters

asset_idstringRequired
The unique identifier of the asset to retrieve.

Response

The asset has been successfully retrieved.
_idstringOptional
The unique identifier of the asset.
methodenumOptional

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
statusenumOptional

Indicates the current processing status of the asset.

A newly uploaded asset starts in the processing status and transitions asynchronously to ready on success or to failed on error, typically within a few seconds to a few minutes. Poll the Retrieve an asset endpoint until the status is ready before you use the asset in different workflows.

Values:

  • processing: The asset is not yet usable. This can mean the upload is still in progress (for example, the platform is still fetching the file from a URL, or a multipart upload has not completed), or the upload has finished and the platform is validating the file. The technical_metadata field is omitted from the response.
  • ready: The platform validated the asset successfully, and the asset is ready to use.
  • failed: The platform could not process the file. The error field describes the reason, and the technical_metadata field may be partially populated.
filenamestringOptional
The name of the file used to create the asset.
file_typestringOptional

The MIME type of the asset file. For documents, this is application/pdf, text/plain, or text/markdown.

created_atstringOptionalformat: "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 anyOptional

User-defined metadata for this asset. This field is absent when no metadata has been set.

sourceobjectOptional

Describes where the asset came from. Present only for assets imported through a connector; absent for assets uploaded directly to the /assets endpoint.

hlsobjectOptional
HLS streaming details for video and audio assets. Present only when HLS generation has been requested.
thumbnailobjectOptional

Thumbnail details for the asset. Present only when thumbnail generation has been requested. PDF files use the first page for the representative thumbnail; text and Markdown files do not produce thumbnails.

technical_metadataobjectOptional

Technical metadata read from the source file of the asset, covering the container, video and audio streams, image properties, document properties, and derived attributes.

The platform populates this object asynchronously after the upload completes. It is omitted from the response while the status of the asset is processing, and it may be partially populated when the status is failed. A field is absent when it does not apply to the type of the asset or when the source file did not contain the corresponding information.

sizelongOptional

The file size of the asset in bytes. The platform sets this value when the asset reaches the ready status.

durationdoubleOptional

The duration of the asset in seconds. Only present for video and audio assets; absent for images and documents. The platform sets this value when the asset reaches the ready status.

errorobjectOptional

The reason the processing failed. The platform returns this field only when status is failed.

Errors

400
Bad Request Error
404
Not Found Error