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