---
title: "Create an asset"
method: POST
path: "/assets"
tags: ["assets"]
---

# Create an asset

`POST /assets`

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 [Retrieve an asset](/v1.3/api-reference/upload-content/direct-uploads/retrieve) endpoint until the status of the asset is `ready` before you use it. 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](/v1.3/docs/concepts/models/marengo#video-file-requirements)
- **Video analysis**: [Pegasus requirements](/v1.3/docs/concepts/models/pegasus#input-requirements)
- **Entity search**: [Marengo image requirements](/v1.3/docs/concepts/models/marengo#image-file-requirements)
- **Create embeddings**: [Marengo requirements](/v1.3/docs/concepts/models/marengo#input-requirements)

<Note title="Note">
This endpoint is rate-limited. For details, see the [Rate limits](/v1.3/docs/get-started/rate-limits) page.
</Note>

## Headers

- `x-api-key` string, required

## Response `201`

The asset has been successfully created.

- Asset — A reference file (image, audio, or video) that you upload to the platform for use in downstream workflows such as indexing, analyzing video content, and creating entities.
  - `_id` string — The unique identifier of the asset.
  - `method` 'direct' | 'url' | 'multipart' — 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` 'failed' | 'processing' | 'ready' — Indicates the current processing status of the asset. A newly uploaded asset starts in the `processing` status and transitions asynchronously to `ready` on success or to `failed` on error, typically within a few seconds to a few minutes. Poll the [Retrieve an asset](/v1.3/api-reference/upload-content/direct-uploads/retrieve) endpoint until the status is `ready` before you use the asset in downstream workflows. **Values**: - `processing`: The asset is not yet usable. This can mean the upload is still in progress (for example, the platform is still fetching the file from a URL, or a multipart upload has not completed), or the upload has finished and the platform is validating the file. The `technical_metadata` field is omitted from the response. - `ready`: The platform validated the asset successfully, and the asset is ready to use. - `failed`: The platform could not process the file. The `error` field describes the reason, and the `technical_metadata` field may be partially populated.
  - `filename` string — The name of the file used to create the asset.
  - `file_type` string — The MIME type of the asset file.
  - `created_at` string, date-time — The date and time, in RFC 3339 format ("YYYY-MM-DDTHH:mm:ssZ"), when the asset was created.
  - `user_metadata` UserMetadata — Metadata that helps you categorize your assets. The object contains user-defined keys and values, where keys are strings and values are one of `string`, `integer`, `float`, or `boolean`. **Example**: ```JSON "user_metadata": { "category": "recentlyAdded", "batchNumber": 5, "rating": 9.3, "needsReview": true } ``` <Note title="Note"> To store other types of data, such as objects or arrays, convert your data into string values before sending it. </Note>
  - `source` AssetSource — Describes where an asset came from. The platform sets this field for assets imported through a connector; it is absent for assets uploaded directly to the `/assets` endpoint.
    - `type` 'connector' — The kind of source.
    - `details` AssetSourceDetails — Provider-specific details about the origin of the file. The fields depend on the value of the `type` field.
      - `provider` 'google_drive' — The data connector provider.
      - `source_id` string — The identifier of the file at the provider. For Google Drive, this is the Drive file identifier.
      - `original_filename` string — The name of the file at the provider when it was imported.
      - `source_link` string — A link to the file at the provider.

## Other responses

- `400` — The request has failed.

---

[API](https://skmtc.net/twelvelabs/apis/twelvelabs-api.md) · [All operations](https://skmtc.net/twelvelabs/apis/twelvelabs-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/twelvelabs/twelvelabs-api/versions/5dbd6e8473c9/schema)