---
title: "Initiate background download for large files"
method: POST
path: "/api/assets/download"
tags: ["asset"]
---

# Initiate background download for large files

`POST /api/assets/download`

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

## Request body

- object
  - `source_url` string, uri, required — URL of the file to download (must be from huggingface.co or civitai.com)
  - `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

## Response `200`

File already exists in storage - asset created/returned immediately

- AssetCreated
  - `id` string, uuid, required — Unique identifier for the asset
  - `name` string, required — Name of the asset file
  - `asset_hash` string — Blake3 hash of the asset content
  - `size` integer, required — Size of the asset in bytes
  - `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, nullable — ID of the preview asset if available
  - `prompt_id` string, uuid, nullable — ID of the job/prompt that created this asset, if available
  - `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
  - `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)
  - `created_new` boolean, required — Whether this was a new asset creation (true) or returned existing (false)

## Other responses

- `202` — Accepted - Download task created and processing in background
- `400` — Invalid URL or unsupported source
- `401` — Unauthorized
- `422` — Validation errors
- `500` — Internal server error

---

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