Create asset

Upload a public HTTPS asset URL. The platform downloads, validates, and stores it in the asset library, then returns the asset ID and uri.

POST /v1/assets
Authorization: Bearer <API_KEY>
Content-Type: application/json

Asset creation is asynchronous. The initial response usually has status=processing. Poll Query asset until it becomes status=active, then use it in video generation.

In video generation requests, use the uri value, such as asset://asset_xxx. Do not pass the raw id. Keep the asset:// prefix.

Request parameters

Parameter	Type	Required	Description
`asset_type`	string	Yes	Asset type: `image`, `video`, or `audio`.
`source_url`	string	Yes	Publicly reachable HTTPS URL. The platform downloads and stores the asset.
`name`	string	No	Asset name for display only. Defaults to a generated name.

Format requirements

Type	Formats	Size limit
Image	`jpeg`, `png`, `webp`, `bmp`, `tiff`, `gif`	Under 30 MB; recommended 300 to 4000 px
Video	`mp4`, `mov`	Under 50 MB; recommended 2 to 5 seconds
Audio	`wav`, `mp3`	Under 15 MB; recommended 2 to 5 seconds

Example

curl -X POST "https://{your-domain}/v1/assets" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "avatar-reference",
    "asset_type": "image",
    "source_url": "https://example.com/avatar-reference.png"
  }'

Success response

HTTP status: 202 Accepted

{
  "id": "asset_6f9a4c2b8d1e3a90",
  "uri": "asset://asset_6f9a4c2b8d1e3a90",
  "object": "asset",
  "asset_type": "image",
  "name": "avatar-reference",
  "status": "processing",
  "created_at": 1779782400,
  "updated_at": 1779782400
}

Response fields

Field	Type	Description
`id`	string	Platform asset ID, formatted as `asset_xxx`.
`uri`	string	Asset URI, formatted as `asset://asset_xxx`. Use this in video generation.
`object`	string	Always `asset`.
`asset_type`	string	Asset type.
`name`	string	Asset name.
`status`	string	Asset status, see below.
`created_at`	integer	Creation time in Unix seconds.
`updated_at`	integer	Last update time in Unix seconds.

Asset statuses

Status	Description	Usable in video generation	Next step
`processing`	The platform has accepted the asset and is storing or processing it.	No	Keep polling
`active`	The asset is ready.	Yes	You can use it in video generation
`failed`	Asset processing failed.	No	Upload again
`disabled`	Asset was disabled by the platform.	No	Contact the platform

Error codes

HTTP status	`error.type`	Scenario
400	`invalid_asset_type`	`asset_type` is not `image`, `video`, or `audio`.
400	`invalid_asset_name`	`name` contains unsupported characters.
400	`invalid_asset_url`	`source_url` is not HTTPS, is not publicly reachable, or is invalid.
503	`asset_store_unavailable`	Asset storage is not configured.

Getting started

Models & billing

Guides

Request parameters

Format requirements

Example

Success response

Response fields

Asset statuses

Error codes

​Request parameters

​Format requirements

​Example

​Success response

​Response fields

​Asset statuses

​Error codes

Request parameters

Format requirements

Example

Success response

Response fields

Asset statuses

Error codes