v1

latestOpenAPI 3.0.22026-07-2610288167.4 KB

asset

Initiate background download for large files

Initiates a background download job for large files from Huggingface or Civitai.

If the file already exists in storage, the asset record is created immediately and returned (200 OK). If the file doesn't exist, a background task is created and the task ID is returned (202 Accepted). The frontend can track progress using GET /api/tasks/{task_id}.

post/api/assets/download

Request body

source_urlstring uri required

URL of the file to download (must be from huggingface.co or civitai.com)

tagsstring[]

Optional tags for the asset (e.g., ["model", "checkpoint"])

user_metadataobject

Optional user-defined metadata to attach to the asset

preview_idstring uuid

Optional preview asset ID to associate with the downloaded asset

Example request

{
  "source_url": "https://huggingface.co/runwayml/stable-diffusion-v1-5/resolve/main/v1-5-pruned.safetensors",
  "preview_id": "550e8400-e29b-41d4-a716-446655440000"
}

Response

File already exists in storage - asset created/returned immediately

idstring uuid required

Unique identifier for the asset

namestring required

Name of the asset file

asset_hashstring

Blake3 hash of the asset content

sizeinteger required

Size of the asset in bytes

mime_typestring

MIME type of the asset

tagsstring[]

Tags associated with the asset

user_metadataobject

Custom user metadata for the asset

preview_urlstring uri

URL for asset preview/thumbnail

preview_idstring uuid nullable

ID of the preview asset if available

prompt_idstring uuid nullable

ID of the job/prompt that created this asset, if available

created_atstring date-time required

Timestamp when the asset was created

updated_atstring date-time required

Timestamp when the asset was last updated

last_access_timestring date-time

Timestamp when the asset was last accessed

is_immutableboolean

Whether this asset is immutable (cannot be modified or deleted)

created_newboolean required

Whether this was a new asset creation (true) or returned existing (false)