Upload a new asset

Uploads a new asset to the system with associated metadata. Supports two upload methods:

1. Direct file upload (multipart/form-data)
2. URL-based upload (application/json with source: “url”)

If an asset with the same hash already exists, returns the existing asset.

POST /api/assets

Upload a new asset

cURL

curl --request POST \
  --url https://cloud.comfy.org/api/assets \
  --header 'Content-Type: multipart/form-data' \
  --header 'X-API-Key: <api-key>' \
  --form file='@example-file' \
  --form 'tags=<string>' \
  --form id=3c90c3cc-0d44-4b50-8888-8dd25736052a \
  --form preview_id=3c90c3cc-0d44-4b50-8888-8dd25736052a \
  --form 'name=<string>' \
  --form 'mime_type=<string>' \
  --form 'user_metadata=<string>'

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

file · file · required

The asset file to upload

tags · string[]

Freeform tags for the asset. Common types include "models", "input", "output", and "temp", but any tag can be used in any order.

id · string<uuid>

Optional asset ID for idempotent creation. If provided and asset exists, returns existing asset.

preview_id · string<uuid>

Optional preview asset ID. If not provided, images will use their own ID as preview.

name · string

Display name for the asset

mime_type · string

MIME type of the asset (e.g., "image/png", "video/mp4")

user_metadata · string

Custom JSON metadata as a string

Response

200

application/json

Asset already exists (returned existing asset)

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)