The AssetsClient class provides methods to upload your media files to the platform. This method creates an asset that you can use in different workflows.

Workflow

Upload your file using the assets.create method. You receive the asset ID in the response.

Asset processing is asynchronous. Poll the assets.retrieve method until the status field is ready before proceeding.

What you do next depends on your use case:

For creating embeddings (videos, audio, images): Use the asset ID with the Embed API v2.
For entity search (images): Use the asset ID to create entities.
For search and analysis (videos): Index your asset using the asset ID.

Methods

Create an asset

Description: 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.

The platform processes uploads asynchronously. This method returns immediately with the asset in the processing status, which then transitions to ready on success or to failed when the file is invalid or corrupt, typically within a few seconds to a few minutes. Poll the assets.retrieve method until the status field is ready before you use the asset. This applies to every upload, including small files.

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 32 MB

Asset creation does not enforce a maximum duration. Each model applies its own file size and duration limits when you index or analyze the asset. For details, see the requirements below.

Additional requirements depend on your workflow:

Search: Marengo requirements
Video analysis: Pegasus requirements
Entity search: Marengo image requirements
Create embeddings: Marengo requirements

Note

This method is rate-limited. For details, see the Rate limits page.

Function signature and example:

1 def create(
2     self,
3     *,
4     method: AssetsCreateRequestMethod,
5     file: typing.Optional[core.File] = OMIT,
6     url: typing.Optional[str] = OMIT,
7     filename: typing.Optional[str] = OMIT,
8     enable_hls: typing.Optional[bool] = OMIT,
9     enable_thumbnail: typing.Optional[bool] = OMIT,
10     user_metadata: typing.Optional[str] = OMIT,
11     request_options: typing.Optional[RequestOptions] = None,
12 ) -> Asset

Parameters

Name	Type	Required	Description
`method`	`AssetsCreateRequestMethod`	Yes	Specifies the upload method for the asset. Use `direct` to upload a local file or `url` for a publicly accessible URL.
`file`	`core.File`	No	The local file to upload. 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 32 MB.
`url`	`str`	No	The publicly accessible URL of a media file to upload. 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 32 MB.
`filename`	`str`	No	The optional filename of the asset. If not provided, the platform determines the filename from the file or URL.
`enable_hls`	`bool`	No	When set to `true`, the platform generates an HLS playlist and segments for streaming. Applicable to video and audio assets only. Default: `false`.
`enable_thumbnail`	`bool`	No	When set to `true`, the platform generates thumbnail images from the uploaded content. Default: `false`.
`user_metadata`	`str`	No	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.
`request_options`	`RequestOptions`	No	Request-specific configuration.

Return value

Returns an object of type Asset representing the created asset.

The Asset class contains the following properties:

Name	Type	Description
`id`	`Optional[str]`	The unique identifier of the asset.
`method`	`Optional[AssetMethod]`	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).
`status`	`Optional[AssetStatus]`	Indicates the current processing status of the asset. Values: `processing` (the asset is not yet usable; the upload is still in progress, or the platform is validating the file), `ready` (the platform validated the asset successfully and it is ready to use), `failed` (the platform could not process the file; the `error` field describes the reason).
`error`	`Optional[AssetError]`	The reason the asset failed. The platform returns this field only when `status` is `failed`.
`filename`	`Optional[str]`	The name of the file used to create the asset.
`file_type`	`Optional[str]`	The MIME type of the asset file.
`size`	`Optional[int]`	The file size of the asset in bytes. Present once the asset finishes processing. The `assets.create` method always returns the asset in the `processing` status and therefore never includes this field.
`duration`	`Optional[float]`	The duration of the asset in seconds. Present for video and audio assets once processing finishes. The `assets.create` method always returns the asset in the `processing` status and therefore never includes this field.
`created_at`	`Optional[datetime]`	The date and time, in RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the asset was created.
`user_metadata`	`Optional[Dict[str, Optional[Any]]]`	User-defined metadata for this asset. This field is absent when no metadata has been set.

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

Create an asset

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

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

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

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 section above) with the following additional properties:

Name	Type	Description
`hls`	`Optional[AssetHls]`	HLS streaming details for the asset. Present only when HLS generation has been requested.
`thumbnail`	`Optional[AssetThumbnail]`	Thumbnail details for the asset. Present only when thumbnail generation has been requested.
`technical_metadata`	`Optional[TechnicalMetadata]`	Technical metadata read from the media file of the asset, covering the container, the individual video and audio streams, image 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 media type of the asset, or when the source file did not carry the corresponding information.

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 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 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 media file in bytes.
`file_mime_type`	`Optional[str]`	The MIME type detected for the source media file.
`file_container_format`	`Optional[str]`	The container format of the source media 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 media 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.

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.

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

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

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

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

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

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 must be of type `string`, and values can be of the following types: `string`, `integer`, `float`, or `boolean`.
`request_options`	`RequestOptions`	No	Request-specific configuration.

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

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 must be of type `string`, and values can be of the following types: `string`, `integer`, `float`, or `boolean`.
`request_options`	`RequestOptions`	No	Request-specific configuration.

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

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