Comfy-Org / Comfy-Org/docs

Issue on docs - (Comfy Cloud API) Clarify "Asset" vs "File" endpoints and document supported sources for URL-based uploads

Open
#754 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
MDX
Stars
288
Forks
206
Avg merge
1d 8h
Merged PRs (30d)
135

Description

Path: /api-reference/cloud/asset/upload-a-new-asset

There is currently ambiguity in the documentation regarding the purpose and limitations of the /api/assets endpoint compared to the standard file upload endpoints. Specifically, the URL-based upload method for assets frequently fails with a UNSUPPORTED_SOURCE error, even when the source is publicly accessible and has no CORS restrictions.

**Error Encountered:** `{ "code": "UNSUPPORTED_SOURCE", "message": "Failed to retrieve asset from external source." }`

**Observed Behavior**: * URL-based uploads fail for multiple media types (MP3, WAV, images) even when hosted on public S3 buckets or direct URLs.

The term "supported source" is not defined, making it impossible to know which domains or protocols are allowed.

It is unclear if assets uploaded via the /api/assets endpoint can actually be used as inputs for workflows/jobs, or if users should strictly be using the multipart form-data method on the file endpoints.

I suggest
- clarifying "Supported Source" Explicitly listing the requirements or allowed domains for the URL-based upload method.
_maybe also add a section explaining the distinction between an **_Asset_** and a **_File_** (uploaded for a specific job/input) could prove beneficial for users referencing the docs._

- Clearly state if assets can be used as workflow inputs and, if so, how to reference them. If they cannot, it would be nice if the documentation could explicitly point users toward the multipart form-data method for workflow inputs as users may be referencing this asset endpoint to upload inputs that are not images due to the confusion caused by the naming convention of [api/upload/image.](https://docs.comfy.org/api-reference/cloud/file/upload-an-image-file) endpoint.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.