The AssetsClient class provides methods to work with assets after you upload them. Use these methods to retrieve and list assets, manage their user-defined metadata, retrieve transcriptions, and delete assets you no longer need.

To create an asset, see the Direct uploads or Multipart uploads page.

Methods

List assets

Description: This method returns a list of assets in your account.

The platform returns your assets sorted by creation date, with the newest at the top of the list.

Function signature and example:

1
def list(
2
    self,
3
    *,
4
    page: typing.Optional[int] = None,
5
    page_limit: typing.Optional[int] = None,
6
    asset_ids: typing.Optional[typing.Union[str, typing.Sequence[str]]] = None,
7
    asset_types: typing.Optional[
8
        typing.Union[AssetsListRequestAssetTypesItem, typing.Sequence[AssetsListRequestAssetTypesItem]]
9
    ] = None,
10
    filename: typing.Optional[str] = None,
11
    request_options: typing.Optional[RequestOptions] = None,
12
) -> SyncPager[AssetDetail]

Parameters

Return value

Returns a SyncPager[AssetDetail] object containing a paginated list of AssetDetail objects. The AssetDetail class extends Asset with additional fields for HLS streaming and thumbnail details. For details about the AssetDetail class, see the Retrieve an asset section below.

The SyncPager[T] class contains the following properties and methods:

API Reference

List assets

Retrieve an asset

Description: This method retrieves details about the specified asset.

Function signature and example:

1
def retrieve(
2
    self,
3
    asset_id: str,
4
    *,
5
    request_options: typing.Optional[RequestOptions] = None
6
) -> AssetDetail

Parameters

Return value

Returns an AssetDetail object containing details about the specified asset.

The AssetDetail class extends Asset (documented in the Create an asset section above) with the following additional properties:

The AssetHls class contains the following properties:

The AssetThumbnail class contains the following properties:

The TechnicalMetadata class contains the following properties:

The VideoStream class contains the following properties:

The AudioStream class contains the following properties:

API Reference

Retrieve an asset

Delete an asset

Description: This method deletes the specified asset. This action cannot be undone. By default, the platform checks whether any indexed assets reference the asset. If references exist, the request fails with a 409 Conflict error. Set the force parameter to true to delete the asset regardless.

Function signature and example:

1
def delete(
2
    self,
3
    asset_id: str,
4
    *,
5
    force: typing.Optional[bool] = None,
6
    request_options: typing.Optional[RequestOptions] = None
7
) -> None

Parameters

Return value

Returns None.

API Reference

Delete asset

Delete the user-defined metadata of an asset

Description: This method deletes the user-defined metadata of the specified asset. To achieve the same result, you can also send an empty object ({}) in the user_metadata field of the replace_user_metadata method.

This action cannot be undone.

Function signature and example:

1
def delete_user_metadata(
2
    self,
3
    asset_id: str,
4
    *,
5
    request_options: typing.Optional[RequestOptions] = None,
6
) -> None

Parameters

Return value

Returns None.

API Reference

Delete the user-defined metadata of an asset

Update the user-defined metadata of an asset

Description: This method updates the user-defined metadata of the specified asset. The platform merges your changes with the existing metadata:

• A key with a value creates or replaces that key.
• A key set to null deletes that key.
• A key set to an empty string ("") is ignored.
• A key you omit from the request keeps its current value.

To replace all metadata in a single call, use the replace_user_metadata method instead.

Function signature and example:

1
def update_user_metadata(
2
    self,
3
    asset_id: str,
4
    *,
5
    user_metadata: UserMetadata,
6
    request_options: typing.Optional[RequestOptions] = None,
7
) -> None

Parameters

Return value

Returns None.

API Reference

Update the user-defined metadata of an asset

Replace the user-defined metadata of an asset

Description: This method replaces the entire user-defined metadata of the specified asset. Unlike the update_user_metadata method, which merges your changes with the existing metadata, this method overwrites the stored value in full:

• A key with a value creates or replaces that key.
• A key set to an empty string ("") or null is ignored.
• A key you omit from the request body is removed.

To clear all metadata, send an empty object ({}) in the user_metadata field. This produces the same result as the delete_user_metadata method.

Function signature and example:

1
def replace_user_metadata(
2
    self,
3
    asset_id: str,
4
    *,
5
    user_metadata: UserMetadata,
6
    request_options: typing.Optional[RequestOptions] = None,
7
) -> None

Parameters

Return value

Returns None.

API Reference

Replace the user-defined metadata of an asset

Error codes

This section lists the most common error messages you may encounter while uploading assets.

• content_type_invalid
  • The content type {content_type} is not supported. Please use multipart/form-data.
• multipart_boundary_missing
  • Multipart boundary is missing. Please provide the boundary in the Content-Type header.
• invalid_multipart
  • Invalid multipart form. Please check your implementation and try again.
• echo bind error
  • (Returns the raw bind error message)
• echo validate error
  • (Returns a validator-generated message, for example: Key: 'CreateAssetRequest.Method' Error:Field validation for 'Method' failed on the 'oneof' tag)
• parameter_not_provided
  • The file parameter is required but was not provided. file is required when method is direct.
  • The url parameter is required but was not provided. url is required when method is url.
• parameter_invalid
  • The method parameter is invalid. To upload in parts, use the /assets/multipart-uploads endpoint.
  • The file parameter is invalid. Unable to process the uploaded file. Please try uploading again.
  • The file parameter is invalid. Unsupported asset type: {asset_type}.
  • The image parameter is invalid. Image dimensions {current_dimensions} are below the minimum {minimum_dimensions}.
  • The image parameter is invalid. Invalid image file. Please check the format and dimensions.
• media_url_unsupported_format
  • The file at the provided URL is not a supported media format. Detected format: {detected_format}. Please provide a valid asset file.
• media_url_not_accessible
  • Cannot access the media URL {url}. The server responded with an error. Please verify the URL is correct and publicly accessible.
• media_url_file_broken
  • Cannot read the media file at the specified URL. Please verify the file is valid and try again.
• media_filesize_too_large
  • The media file is too large. Please upload a file smaller than {maximum_size}. The current size is {current_size}.
• video_file_broken
  • Unable to process video file. Please check if the file is valid and try again.
• video_file_live
  • Live video streams are not supported. Please provide a URL that is not a live stream.
• video_resolution_too_low
  • The resolution of the video is too low. Please upload a video with a resolution between {minimum_resolution} and {maximum_resolution}. Current resolution is {current_resolution}.
• video_resolution_too_high
  • The resolution of the video is too high. Please upload a video with a resolution between {minimum_resolution} and {maximum_resolution}. Current resolution is {current_resolution}.
• video_resolution_invalid_aspect_ratio
  • The aspect ratio of the video is invalid. Please upload a video with an aspect ratio between 1:1 and {maximum_aspect_ratio}. Current resolution is {current_resolution}.
• video_duration_too_short
  • The video is too short. Please use a video with a duration of at least {minimum_duration} seconds. Current duration is {current_duration} seconds.
• video_duration_too_long
  • The video is too long. Please use a video with a duration between {minimum_duration} and {maximum_duration} seconds. Current duration is {current_duration} seconds.
• video_filesize_too_large
  • The video is too large. Please use a video with a size less than {maximum_size}. The current size is {current_size}.
• audio_file_broken
  • Unable to process audio file. Please check if the file is valid and try again.
• audio_duration_too_short
  • The audio is too short. Please use an audio file with a duration of at least {minimum_duration} seconds. Current duration is {current_duration} seconds.
• audio_duration_too_long
  • The audio is too long. Please use an audio file with a duration between {minimum_duration} and {maximum_duration} seconds. Current duration is {current_duration} seconds.
• audio_filesize_too_large
  • The audio is too large. Please use an audio file with a size less than {maximum_size}. The current size is {current_size}.
• audio_format_unsupported
  • The audio format {format} is not supported. Please use one of the following formats: {supported_formats}.
• asset_transcription_not_found
  • Transcription for asset {asset_id} does not exist.
• resource_not_exists
  • The requested asset with the identifier {asset_id} does not exist.

For a list of general errors that apply to all endpoints, see the Error codes page.

Retrieve the transcription of an asset

Description: This method retrieves the transcription of a video or audio asset. An asset that has a transcription returns 200 with the current transcription status. The endpoint returns 404 when the asset cannot be found or has no transcription.

The platform generates transcriptions asynchronously. Poll this endpoint to monitor the transcription status.

When the status is ready, the response contains the segmentations you requested that the transcription supports. A transcription does not always support every segmentation, so read the segmentations the response returns rather than assuming every requested one is present.

Function signature and example:

1
def retrieve_transcription(
2
    self,
3
    asset_id: str,
4
    *,
5
    include: typing.Optional[
6
        typing.Union[
7
            AssetsRetrieveTranscriptionRequestIncludeItem,
8
            typing.Sequence[AssetsRetrieveTranscriptionRequestIncludeItem],
9
        ]
10
    ] = None,
11
    request_options: typing.Optional[RequestOptions] = None,
12
) -> AssetTranscriptionResponse

Parameters

Return value

Returns an AssetTranscriptionResponse object containing the transcription status and the transcriptions you requested.

The AssetTranscriptionResponse class contains the following properties:

The AssetTranscriptionEntry class contains the following properties:

The AssetTranscriptionUtterance class contains the following properties:

The AssetTranscriptionError class contains the following properties:

API Reference

Retrieve the transcription of an asset