Sign in
assets

Retrieve an asset

This method retrieves details about the specified asset.

get/assets/{asset_id}

Path parameters

asset_idstring required

The unique identifier of the asset to retrieve.

Headers

x-api-keystring required

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>

Response

The asset has been successfully retrieved.

_idstring

The unique identifier of the asset.

method'direct' | 'url' | 'multipart' | 'connector'

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'failed' | 'processing' | 'ready'

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.
filenamestring

The name of the file used to create the asset.

file_typestring

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

created_atstring date-time

The date and time, in RFC 3339 format ("YYYY-MM-DDTHH:mm:ssZ"), when the asset was created.

user_metadataUserMetadata

Metadata that helps you categorize your assets. The object contains user-defined keys and values, where keys are strings and values are one of string, integer, float, or boolean.

Example:

"user_metadata": {
  "category": "recentlyAdded",
  "batchNumber": 5,
  "rating": 9.3,
  "needsReview": true
}
<Note title="Note"> To store other types of data, such as objects or arrays, convert your data into string values before sending it. </Note>
sizeinteger

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

durationnumber double

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.

Changes

Changed in 4 of the 12 revisions of this API.217

  • 03b6cc37a53716See the full diff
    • ○

      added the non-success response with the status

      response-non-success-status-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

  • 9c12cd88093a1See the full diff
    • ●

      added the new connector enum value to the response property for the response status

      response-property-enum-value-added

  • 5dbd6e8473c91See the full diff
    • ●

      removed the optional property from the response with the status

      response-optional-property-removed

  • c0926990c6621See the full diff
    • ○

      added the optional property to the response with the status

      response-optional-property-added

    This revision also has 35 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog