> 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. # Manage assets > Retrieve assets, manage user-defined metadata, and retrieve transcriptions. 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](/v1.3/sdk-reference/python/upload-files/direct-uploads) or [Multipart uploads](/v1.3/sdk-reference/python/upload-files/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**: **`Function signature`** ```python Function signature def list( self, *, page: typing.Optional[int] = None, page_limit: typing.Optional[int] = None, asset_ids: typing.Optional[typing.Union[str, typing.Sequence[str]]] = None, asset_types: typing.Optional[ typing.Union[AssetsListRequestAssetTypesItem, typing.Sequence[AssetsListRequestAssetTypesItem]] ] = None, filename: typing.Optional[str] = None, request_options: typing.Optional[RequestOptions] = None, ) -> SyncPager[AssetDetail] ``` **`Python example`** ```python Python example from twelvelabs import TwelveLabs response = client.assets.list( page=1, page_limit=10, ) print("Assets:") for asset in response: print(f" ID: {asset.id}") print(f" Filename: {asset.filename}") print(f" Status: {asset.status}") print(f" Created: {asset.created_at}") ``` ### Parameters | Name | Type | Required | Description | | ----------------- | ----------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `page` | `int` | No | A number that identifies the page to retrieve. Default: `1`. | | `page_limit` | `int` | No | The number of items to return on each page. Default: `10`. Max: `50`. | | `asset_ids` | `Union[str, Sequence[str]]` | No | Filters the response to include only assets with the specified IDs. Provide one or more asset IDs. When you specify multiple IDs, the platform returns all matching assets. | | `asset_types` | `Union[AssetsListRequestAssetTypesItem, Sequence[AssetsListRequestAssetTypesItem]]` | No | Filters the response to include only assets of the specified types. Provide one or more asset types. When you specify multiple types, the platform returns all matching assets. Values: `image`, `video`, `audio`, `document`. | | `filename` | `str` | No | Filters the response to include only assets whose filename contains the specified string. The match is case-insensitive and supports partial matching. | | `request_options` | `RequestOptions` | No | Request-specific configuration. | ### 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](/v1.3/sdk-reference/python/manage-assets#retrieve-an-asset) section below. The `SyncPager[T]` class contains the following properties and methods: | Name | Type | Description | | -------------- | ------------------------------------------------ | ---------------------------------------------------------------------- | | `items` | `Optional[List[T]]` | A list containing the current page of items. Can be `None`. | | `has_next` | `bool` | Indicates whether there is a next page to load. | | `get_next` | `Optional[Callable[[], Optional[SyncPager[T]]]]` | A callable function that retrieves the next page. Can be `None`. | | `response` | `Optional[BaseHttpResponse]` | The HTTP response object. Can be `None`. | | `next_page()` | `Optional[SyncPager[T]]` | Calls `get_next()` if available and returns the next page object. | | `__iter__()` | `Iterator[T]` | Allows iteration through all items across all pages using `for` loops. | | `iter_pages()` | `Iterator[SyncPager[T]]` | Allows iteration through page objects themselves. | ### API Reference [List assets](/v1.3/api-reference/upload-content/direct-uploads/list) ## Retrieve an asset **Description**: This method retrieves details about the specified asset. **Function signature and example**: **`Function signature`** ```python Function signature def retrieve( self, asset_id: str, *, request_options: typing.Optional[RequestOptions] = None ) -> AssetDetail ``` **`Python example`** ```python Python example from twelvelabs import TwelveLabs asset = client.assets.retrieve( asset_id="", ) print(f"Asset ID: {asset.id}") print(f"Filename: {asset.filename}") print(f"Status: {asset.status}") print(f"File type: {asset.file_type}") print(f"Method: {asset.method}") print(f"Created at: {asset.created_at}") ``` ### Parameters | Name | Type | Required | Description | | ----------------- | ---------------- | -------- | ----------------------------------------------- | | `asset_id` | `str` | Yes | The unique identifier of the asset to retrieve. | | `request_options` | `RequestOptions` | No | Request-specific configuration. | ### Return value Returns an `AssetDetail` object containing details about the specified asset. The `AssetDetail` class extends `Asset` (documented in the [Create an asset](/v1.3/sdk-reference/python/upload-files/direct-uploads#create-an-asset) section above) with the following additional properties: | Name | Type | Description | | -------------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `hls` | `Optional[AssetHls]` | HLS streaming details for video and audio assets. Present only when HLS generation has been requested. | | `thumbnail` | `Optional[AssetThumbnail]` | 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_metadata` | `Optional[TechnicalMetadata]` | 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. | | `size` | `Optional[int]` | The file size of the asset in bytes. The platform sets this value when the asset reaches the `ready` status. | | `duration` | `Optional[float]` | 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. | | `error` | `Optional[AssetError]` | The reason the processing failed. The platform returns this field only when `status` is `failed`. | The `AssetHls` class contains the following properties: | Name | Type | Description | | -------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `manifest_url` | `Optional[str]` | The URL of the HLS manifest file for streaming. Only present when the status of the HLS stream is `ready`. | | `status` | `Optional[AssetHlsStatus]` | The status of the HLS stream. Values: `pending` (the platform has not yet started HLS generation), `processing` (the platform is generating HLS segments), `ready` (the HLS stream is ready for playback), `error` (HLS generation failed). | The `AssetThumbnail` class contains the following properties: | Name | Type | Description | | -------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `representative_url` | `Optional[str]` | The URL of the representative thumbnail image. Only present when the status of the thumbnail is `ready`. | | `status` | `Optional[AssetThumbnailStatus]` | The status of the thumbnail. Values: `pending` (the platform has not yet started thumbnail generation), `processing` (the platform is generating the thumbnail), `ready` (the thumbnail is ready), `error` (thumbnail generation failed). | The `TechnicalMetadata` class contains the following properties: | Name | Type | Description | | ---------------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `file_size_bytes` | `Optional[int]` | The size of the source file in bytes. | | `file_mime_type` | `Optional[str]` | The MIME type detected for the source file. | | `file_container_format` | `Optional[str]` | The container format of the source file. When a container maps to several format names, the platform reports them as a comma-separated list. | | `container_creation_time` | `Optional[datetime]` | The creation time recorded in the source file container, in RFC 3339 format ("YYYY-MM-DDTHH:mm:ssZ"), when present. | | `video_streams` | `Optional[List[VideoStream]]` | The video streams contained in the media file. | | `video_codec` | `Optional[str]` | The codec of the primary video stream. | | `video_width` | `Optional[int]` | The pixel width of the primary video stream. | | `video_height` | `Optional[int]` | The pixel height of the primary video stream. | | `video_fps` | `Optional[float]` | The frame rate of the primary video stream, in frames per second. | | `video_duration_seconds` | `Optional[float]` | The duration of the primary video stream, in seconds. | | `video_bitrate_bps` | `Optional[int]` | The bit rate of the primary video stream, in bits per second. | | `audio_streams` | `Optional[List[AudioStream]]` | The audio streams contained in the media file. | | `audio_codec` | `Optional[str]` | The codec of the primary audio stream. | | `audio_sample_rate` | `Optional[int]` | The sample rate of the primary audio stream, in hertz. | | `audio_channels` | `Optional[int]` | The number of channels in the primary audio stream. | | `audio_duration_seconds` | `Optional[float]` | The duration of the primary audio stream, in seconds. | | `start_timecode` | `Optional[str]` | The starting SMPTE timecode of the media, when present. | | `timecode_source` | `Optional[str]` | The source from which the starting timecode was derived. | | `drop_frame` | `Optional[bool]` | Whether the timecode uses drop-frame numbering. | | `image_width` | `Optional[int]` | The pixel width of the image. | | `image_height` | `Optional[int]` | The pixel height of the image. | | `image_format` | `Optional[str]` | The format of the image. | | `image_orientation` | `Optional[int]` | The EXIF orientation value of the image. | | `image_color_space` | `Optional[str]` | The color space of the image. | | `image_bit_depth` | `Optional[int]` | The bit depth per channel of the image. | | `is_hdr` | `Optional[bool]` | Whether the media is high dynamic range (HDR). | | `has_audio` | `Optional[bool]` | Whether the media contains at least one audio stream. | | `has_alpha` | `Optional[bool]` | Whether the image contains an alpha (transparency) channel. | | `is_animated` | `Optional[bool]` | Whether the image is animated (for example, an animated GIF or WebP). | | `total_video_streams` | `Optional[int]` | The total number of video streams in the media file. | | `total_audio_streams` | `Optional[int]` | The total number of audio streams in the media file. | | `storage_aspect_ratio` | `Optional[float]` | The storage aspect ratio of the video (pixel width divided by pixel height). | | `geospatial_latitude` | `Optional[float]` | The GPS latitude embedded in the source media, in decimal degrees. Present only when the source media carries location metadata. | | `geospatial_longitude` | `Optional[float]` | The GPS longitude embedded in the source media, in decimal degrees. Present only when the source media carries location metadata. | | `geospatial_altitude_meters` | `Optional[float]` | The GPS altitude embedded in the source media, in meters. Present only when the source media carries location metadata. | | `document_page_count` | `Optional[int]` | The number of pages in the PDF file. | | `document_pdf_version` | `Optional[str]` | The PDF version specified in the file. | | `document_page_width_pt` | `Optional[float]` | The width of the first page, in points. | | `document_page_height_pt` | `Optional[float]` | The height of the first page, in points. | | `document_is_tagged` | `Optional[bool]` | Whether the PDF file is tagged for accessibility. An explicit `false` is meaningful. | | `document_is_encrypted` | `Optional[bool]` | Whether the PDF file is encrypted. An explicit `false` is meaningful. | | `document_language` | `Optional[str]` | The language specified in the PDF file, when present. | | `document_title` | `Optional[str]` | The title from the PDF metadata, when present. | | `document_author` | `Optional[str]` | The author from the PDF metadata, when present. | | `document_subject` | `Optional[str]` | The subject from the PDF metadata, when present. | | `document_keywords` | `Optional[str]` | The keywords from the PDF metadata, when present. | | `document_creator_tool` | `Optional[str]` | The application that created the PDF file, when present. | | `document_producer` | `Optional[str]` | The application that produced the PDF file, when present. | | `document_creation_date` | `Optional[datetime]` | The normalized creation date from the PDF file, in RFC 3339 format, when present. | | `document_modification_date` | `Optional[datetime]` | The normalized modification date from the PDF file, in RFC 3339 format, when present. | The `VideoStream` class contains the following properties: | Name | Type | Description | | ---------------------- | ----------------- | --------------------------------------------------------------------------- | | `index` | `Optional[int]` | The zero-based index of the stream within the media file. | | `codec` | `Optional[str]` | The codec of the video stream. | | `width` | `Optional[int]` | The pixel width of the video stream. | | `height` | `Optional[int]` | The pixel height of the video stream. | | `fps` | `Optional[float]` | The nominal frame rate of the video stream, in frames per second. | | `avg_fps` | `Optional[float]` | The average frame rate of the video stream, in frames per second. | | `duration_seconds` | `Optional[float]` | The duration of the video stream, in seconds. | | `bitrate_bps` | `Optional[int]` | The bit rate of the video stream, in bits per second. | | `rotation` | `Optional[int]` | The rotation applied to the video stream, in degrees. | | `pixel_aspect_ratio` | `Optional[str]` | The pixel (sample) aspect ratio of the video stream. | | `display_aspect_ratio` | `Optional[str]` | The display aspect ratio of the video stream. | | `scan_type` | `Optional[str]` | The scan type of the video stream (for example, progressive or interlaced). | | `pixel_format` | `Optional[str]` | The pixel format of the video stream. | | `bit_depth` | `Optional[int]` | The bit depth per color component of the video stream. | | `color_range` | `Optional[str]` | The color range of the video stream. | | `color_transfer` | `Optional[str]` | The color transfer characteristics of the video stream. | | `color_space` | `Optional[str]` | The color space of the video stream. | | `color_primaries` | `Optional[str]` | The color primaries of the video stream. | The `AudioStream` class contains the following properties: | Name | Type | Description | | ------------------ | ----------------- | --------------------------------------------------------- | | `index` | `Optional[int]` | The zero-based index of the stream within the media file. | | `codec` | `Optional[str]` | The codec of the audio stream. | | `codec_long` | `Optional[str]` | The descriptive long name of the audio codec. | | `sample_rate` | `Optional[int]` | The sample rate of the audio stream, in hertz. | | `bit_depth` | `Optional[int]` | The bit depth of the audio stream. | | `channels` | `Optional[int]` | The number of channels in the audio stream. | | `channel_layout` | `Optional[str]` | The channel layout of the audio stream. | | `bitrate_bps` | `Optional[int]` | The bit rate of the audio stream, in bits per second. | | `language` | `Optional[str]` | The language of the audio stream, when present. | | `duration_seconds` | `Optional[float]` | The duration of the audio stream, in seconds. | The `AssetError` class contains the following properties: | Name | Type | Description | | --------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `message` | `Optional[str]` | A human-readable message describing the failure, such as a corrupted or unsupported file, a file the platform could not access, or a video that failed a playability check. The exact text is not part of the contract. Do not parse it. | ### API Reference [Retrieve an asset](/v1.3/api-reference/upload-content/direct-uploads/retrieve) ## 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**: **`Function signature`** ```python Function signature def delete( self, asset_id: str, *, force: typing.Optional[bool] = None, request_options: typing.Optional[RequestOptions] = None ) -> None ``` **`Python example`** ```python Python example from twelvelabs import TwelveLabs client.assets.delete( asset_id="", force=True, ) ``` ### Parameters | Name | Type | Required | Description | | ----------------- | ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `asset_id` | `str` | Yes | The unique identifier of the asset to delete. | | `force` | `bool` | No | When set to `true`, the platform deletes the asset even if indexed assets reference it. When set to `false` or omitted, the request fails with `409 Conflict` if references exist. Default: `false`. | | `request_options` | `RequestOptions` | No | Request-specific configuration. | ### Return value Returns `None`. ### API Reference [Delete asset](/v1.3/api-reference/upload-content/direct-uploads/delete) ## 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`](#replace-the-user-defined-metadata-of-an-asset) method. This action cannot be undone. **Function signature and example**: **`Function signature`** ```python Function signature def delete_user_metadata( self, asset_id: str, *, request_options: typing.Optional[RequestOptions] = None, ) -> None ``` **`Python example`** ```python Python example from twelvelabs import TwelveLabs client.assets.delete_user_metadata( asset_id="", ) ``` ### Parameters | Name | Type | Required | Description | | ----------------- | ---------------- | -------- | ------------------------------------------------------------------------- | | `asset_id` | `str` | Yes | The unique identifier of the asset whose user-defined metadata to delete. | | `request_options` | `RequestOptions` | No | Request-specific configuration. | ### Return value Returns `None`. ### API Reference [Delete the user-defined metadata of an asset](/v1.3/api-reference/upload-content/direct-uploads/delete-user-metadata) ## 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`](#replace-the-user-defined-metadata-of-an-asset) method instead. **Function signature and example**: **`Function signature`** ```python Function signature def update_user_metadata( self, asset_id: str, *, user_metadata: UserMetadata, request_options: typing.Optional[RequestOptions] = None, ) -> None ``` **`Python example`** ```python Python example from twelvelabs import TwelveLabs client.assets.update_user_metadata( asset_id="", user_metadata={ "category": "recentlyAdded", "batchNumber": 5, "rating": 9.3, "needsReview": True, }, ) ``` ### Parameters | Name | Type | Required | Description | | ----------------- | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------- | | `asset_id` | `str` | Yes | The unique identifier of the asset whose user-defined metadata to update. | | `user_metadata` | `UserMetadata` | Yes | The metadata to set or update. Keys are strings, and values can be a string, a number, a boolean, or an array of strings. | | `request_options` | `RequestOptions` | No | Request-specific configuration. | ### Return value Returns `None`. ### API Reference [Update the user-defined metadata of an asset](/v1.3/api-reference/upload-content/direct-uploads/update-user-metadata) ## 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`](#update-the-user-defined-metadata-of-an-asset) 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`](#delete-the-user-defined-metadata-of-an-asset) method. **Function signature and example**: **`Function signature`** ```python Function signature def replace_user_metadata( self, asset_id: str, *, user_metadata: UserMetadata, request_options: typing.Optional[RequestOptions] = None, ) -> None ``` **`Python example`** ```python Python example from twelvelabs import TwelveLabs client.assets.replace_user_metadata( asset_id="", user_metadata={ "category": "recentlyAdded", "batchNumber": 5, "rating": 9.3, "needsReview": True, }, ) ``` ### Parameters | Name | Type | Required | Description | | ----------------- | ---------------- | -------- | --------------------------------------------------------------------------------------------------------------- | | `asset_id` | `str` | Yes | The unique identifier of the asset whose user-defined metadata to replace. | | `user_metadata` | `UserMetadata` | Yes | The metadata to set. Keys are strings, and values can be a string, a number, a boolean, or an array of strings. | | `request_options` | `RequestOptions` | No | Request-specific configuration. | ### Return value Returns `None`. ### API Reference [Replace the user-defined metadata of an asset](/v1.3/api-reference/upload-content/direct-uploads/replace-user-metadata) ## Enable storage accounting for an asset **Description**: This method enables storage accounting for the specified asset. Storage accounting makes an asset count toward your Managed Intelligence allowance. **When to use this method**: Call it once for each asset that you uploaded before your plan moved to the new billing (a pre-migration asset). Enable storage accounting before you do either of the following: * Add the asset to a knowledge store. * Index the asset in an index for which Marengo is enabled. An asset that you upload after your plan moves already counts toward your Managed Intelligence allowance. You do not need to call this method for it. **Before you call this method**: * Your plan must have moved to the new billing. * The asset must have the `ready` status and a recorded size. To check, use the [`retrieve`](#retrieve-an-asset) method and read the `status` and `size` fields. * The asset must fit in your Managed Intelligence allowance. **After you call this method**: * The asset counts toward your Managed Intelligence allowance from the moment of the call. * Enabling storage accounting is permanent. You cannot turn it off. * If storage accounting is already on, the method returns the same response and changes nothing. **Function signature and example**: **`Function signature`** ```python Function signature def enable_storage_accounting( self, asset_id: str, *, enabled: bool, request_options: typing.Optional[RequestOptions] = None, ) -> AssetStorageAccounting ``` **`Python example`** ```python Python example from twelvelabs import TwelveLabs result = client.assets.enable_storage_accounting( asset_id="", enabled=True, ) print(f"Storage accounting: {result.storage_accounting}") ``` ### Parameters | Name | Type | Required | Description | | ----------------- | ---------------- | -------- | ---------------------------------------------------------------------------- | | `asset_id` | `str` | Yes | The unique identifier of the asset for which to enable storage accounting. | | `enabled` | `bool` | Yes | Enables storage accounting for the asset. The only accepted value is `true`. | | `request_options` | `RequestOptions` | No | Request-specific configuration. | ### Return value Returns an `AssetStorageAccounting` object containing the storage accounting setting of the asset. The `AssetStorageAccounting` class contains the following properties: | Name | Type | Description | | -------------------- | ------ | ------------------------------------------------------------------------------------------- | | `asset_id` | `str` | The unique identifier of the asset. | | `storage_accounting` | `bool` | Indicates whether the platform counts the asset toward your Managed Intelligence allowance. | | `bytes` | `int` | The number of stored bytes that the platform counts for the asset. | ### API Reference [Enable storage accounting for an asset](/v1.3/api-reference/manage-assets/enable-storage-accounting) # 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 `enabled` parameter is invalid. Storage accounting cannot be turned off once an asset is billable. * 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. * Resource with id `{asset_id}` does not exist. * `asset_not_ready_for_storage_billing` * Storage accounting cannot be enabled. Asset `{asset_id}` is still being processed; try again once it is ready. * Storage accounting cannot be enabled. Asset `{asset_id}` failed to process, so it will never become ready. * Storage accounting cannot be enabled. Asset `{asset_id}` is not ready. * `asset_storage_size_unknown` * Storage accounting cannot be enabled. Asset `{asset_id}` has no recorded size. * `asset_storage_limit_exceeded` * Storage capacity exceeded for your plan. Current: `{current_bytes}`, Limit: `{limit_bytes}`, Requested: `{requested_bytes}`. * `platform_billing_not_active` * This account has no effective Platform billing plan. * `asset_storage_accounting_required` * Asset `{asset_id}` must have storage accounting enabled before indexing or ingestion under the new billing. Call `PUT /assets/{asset_id}/storage-accounting` with `{"enabled":true}`, then retry indexing or ingestion. For a list of general errors that apply to all endpoints, see the [Error codes](/v1.3/api-reference/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**: **`Function signature`** ```python Function signature def retrieve_transcription( self, asset_id: str, *, include: typing.Optional[ typing.Union[ AssetsRetrieveTranscriptionRequestIncludeItem, typing.Sequence[AssetsRetrieveTranscriptionRequestIncludeItem], ] ] = None, request_options: typing.Optional[RequestOptions] = None, ) -> AssetTranscriptionResponse ``` **`Python example`** ```python Python example from twelvelabs import TwelveLabs transcription = client.assets.retrieve_transcription( asset_id="", include=["words", "utterances"], ) print(f"Status: {transcription.status}") ``` ### Parameters | Name | Type | Required | Description | | ----------------- | ------------------------------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `asset_id` | `str` | Yes | The unique identifier of the asset. | | `include` | `Optional[Union[AssetsRetrieveTranscriptionRequestIncludeItem, Sequence[AssetsRetrieveTranscriptionRequestIncludeItem]]]` | No | Specifies the transcriptions to return. Each value segments the transcription differently: `words` returns one entry for each word, `sentences` returns one entry for each chunk the speech recognition model detects as a sentence, and `utterances` returns one entry for each speaker turn. Default: `words`. | | `request_options` | `RequestOptions` | No | Request-specific configuration. | ### Return value Returns an `AssetTranscriptionResponse` object containing the transcription status and the transcriptions you requested. The `AssetTranscriptionResponse` class contains the following properties: | Name | Type | Description | | ------------ | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `status` | `AssetTranscriptionStatus` | The current status of the transcription. Values: `pending` (the platform has not started the transcription), `processing` (the platform is transcribing the asset), `ready` (the transcription is available), `failed` (the platform could not transcribe the asset). | | `words` | `Optional[List[AssetTranscriptionEntry]]` | One entry for each word. Present when the status is `ready`, the `include` parameter lists `words`, and the transcription supports word-level segmentation. | | `sentences` | `Optional[List[AssetTranscriptionEntry]]` | One entry for each chunk the speech recognition model detects as a sentence. Present when the status is `ready`, the `include` parameter lists `sentences`, and the transcription supports sentence-level segmentation. | | `utterances` | `Optional[List[AssetTranscriptionUtterance]]` | One entry for each speaker turn. Present when the status is `ready`, the `include` parameter lists `utterances`, and the transcription supports speaker-turn segmentation. | | `error` | `Optional[AssetTranscriptionError]` | Details about the failure. Present when the status is `failed`. | The `AssetTranscriptionEntry` class contains the following properties: | Name | Type | Description | | ------- | ------- | --------------------------------------- | | `start` | `float` | The start timestamp in seconds. | | `end` | `float` | The end timestamp in seconds. | | `value` | `str` | The recognized text in this time range. | The `AssetTranscriptionUtterance` class contains the following properties: | Name | Type | Description | | --------- | --------------- | ----------------------------------------- | | `start` | `float` | The start timestamp in seconds. | | `end` | `float` | The end timestamp in seconds. | | `value` | `str` | The recognized text in this speaker turn. | | `speaker` | `Optional[str]` | The speaker identifier when available. | The `AssetTranscriptionError` class contains the following properties: | Name | Type | Description | | --------- | ----- | ------------------------------------------------------------------------------------------------------------- | | `message` | `str` | A human-readable message describing the failure. The exact text is not part of the contract. Do not parse it. | ### API Reference [Retrieve the transcription of an asset](/v1.3/api-reference/manage-assets/retrieve-transcription)