Python SDKAssetsUpload files

Direct uploads

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

Workflow

1

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

2

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

3

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 reusable files that you can use in different workflows.

The platform processes uploads asynchronously. This method returns immediately with the asset in the processing status, which then transitions to the ready status on success or to the failed status when the file is invalid, corrupt, or unreadable, 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.
  • PDF, text, and Markdown files.

Filename extension matching is case-insensitive; for example, notes.MD and notes.md are treated the same. The platform rejects unsupported formats. For documents, it also rejects files whose extensions don’t match the detected content.

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
  • Documents, local files: Up to 200 MB
  • Documents, public URLs: Up to 512 MB

Asset creation does not enforce a maximum duration for video and audio files. Each model applies its own file size and duration limits. For details, see the requirements below.

Additional requirements depend on your workflow:

Note

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

Function signature and example:

1def 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

NameTypeRequiredDescription
methodAssetsCreateRequestMethodYesSpecifies the upload method for the asset. Use direct to upload a local file or url for a publicly accessible URL.
filecore.FileNoThe local file to upload. This parameter is required when method is set to direct.

Local video, audio, and documents support up to 200 MB. Images support up to 32 MB.
urlstrNoThe publicly accessible URL of a media file or document 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. Document URLs support up to 512 MB.
filenamestrNoThe filename of the asset. If you provide a filename, the platform preserves it. If you omit it, the platform determines one from the file or URL.
enable_hlsboolNoWhen set to true, the platform generates an HLS playlist and segments for streaming. Applicable to video and audio assets only. The platform ignores this flag for other asset types. Default: false.
enable_thumbnailboolNoWhen set to true, the platform generates thumbnail images from the uploaded content. For PDF files, the representative thumbnail uses the first page. Text and Markdown files do not produce thumbnails; the platform ignores this flag for them. Default: false.
user_metadatastrNoMetadata 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_optionsRequestOptionsNoRequest-specific configuration.

Return value

Returns an object of type Asset representing the created asset.

The Asset class contains the following properties:

NameTypeDescription
idOptional[str]The unique identifier of the asset.
methodOptional[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).
statusOptional[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).
filenameOptional[str]The name of the file used to create the asset.
file_typeOptional[str]The MIME type of the asset file. For documents, this is application/pdf, text/plain, or text/markdown.
created_atOptional[datetime]The date and time, in RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the asset was created.
user_metadataOptional[Dict[str, Optional[Any]]]User-defined metadata for this asset. This field is absent when no metadata has been set.
sourceOptional[AssetSource]Describes where the asset came from. Present only for assets imported through a connector; absent for assets uploaded directly to the /assets endpoint.

API Reference

Create an asset