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

POST /api/assets/download

Initiate background download for large files

cURL

curl --request POST \
  --url https://cloud.comfy.org/api/assets/download \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "source_url": "https://huggingface.co/runwayml/stable-diffusion-v1-5/resolve/main/v1-5-pruned.safetensors",
  "tags": [
    "<string>"
  ],
  "user_metadata": {},
  "preview_id": "550e8400-e29b-41d4-a716-446655440000"
}
'

200

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "size": 123,
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "created_new": true,
  "asset_hash": "<string>",
  "mime_type": "<string>",
  "tags": [
    "<string>"
  ],
  "user_metadata": {},
  "preview_url": "<string>",
  "preview_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "prompt_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "last_access_time": "2023-11-07T05:31:56Z",
  "is_immutable": true
}

Authorizations

X-API-Key · string · header · required

API key authentication. Generate an API key from your account settings at https://comfy.org/account. Pass the key in the X-API-Key header.

Body

application/json

source_url · string<uri> · required

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

Example:

"https://huggingface.co/runwayml/stable-diffusion-v1-5/resolve/main/v1-5-pruned.safetensors"

tags · string[]

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

user_metadata · object

Optional user-defined metadata to attach to the asset

preview_id · string<uuid>

Optional preview asset ID to associate with the downloaded asset

Example:

"550e8400-e29b-41d4-a716-446655440000"

Response

200

application/json

File already exists in storage - asset created/returned immediately

id · string<uuid> · required

Unique identifier for the asset

name · string · required

Name of the asset file

size · integer<int64> · required

Size of the asset in bytes

created_at · string<date-time> · required

Timestamp when the asset was created

updated_at · string<date-time> · required

Timestamp when the asset was last updated

created_new · boolean · required

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

asset_hash · string

Blake3 hash of the asset content

mime_type · string

MIME type of the asset

tags · string[]

Tags associated with the asset

user_metadata · object

Custom user metadata for the asset

preview_url · string<uri>

URL for asset preview/thumbnail

preview_id · string<uuid> | null

ID of the preview asset if available

prompt_id · string<uuid> | null

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

last_access_time · string<date-time>

Timestamp when the asset was last accessed

is_immutable · boolean

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