docs: add Assets API documentation#743
Conversation
|
Closing - will create a new PR for local ComfyUI server docs instead of cloud API |
- Add comprehensive Assets API section with list, upload, get, tags, delete - Add legacy note to existing /api/upload/* section - Recommend Assets API for new integrations Amp-Thread-ID: https://ampcode.com/threads/T-019c0c6f-94c9-70a9-90c7-dee4048a242d Co-authored-by: Amp <amp@ampcode.com>
- Add /api/assets endpoints to routes table with (recommended) label - Mark /upload/image, /upload/mask, /view as (legacy) - Add detailed Assets API section with parameters, response examples - Update both English and Chinese translations Amp-Thread-ID: https://ampcode.com/threads/T-019c0c6f-94c9-70a9-90c7-dee4048a242d Co-authored-by: Amp <amp@ampcode.com>
Amp-Thread-ID: https://ampcode.com/threads/T-019c0cd7-4eea-71d7-91d1-6b7288070d65 Co-authored-by: Amp <amp@ampcode.com>
christian-byrne
force-pushed
the
docs/recommend-assets-api
branch
from
3e74487 to
764312c
Compare
There was a problem hiding this comment.
Inline anchors below. Broader gaps not anchored to a single line:
- No error-response documentation anywhere. No 400 / 401 / 403 / 404 / 409 / 413 / 422 / 429 status codes, no error-payload schema, no retry guidance. The cloud API has a standard error envelope (
{error_code, message, details}) that should be referenced here. - Cloud reference has no way to retrieve file bytes after upload.
GET /api/assets/{id}/contentis incomms_routes.mdx(line 32) but absent fromdevelopment/cloud/api-reference.mdx— list/upload/details/tags/delete are documented but download is not. - No upload constraints. Max file size, allowed MIME types,
user_metadatasize/depth limits, dedup behavior on duplicate upload (200 vs 201 vs 409, id reuse), tag count/length limits, quota/retention — none documented. Especially load-bearing because the page markets the API for "models" without saying whether multi-GB checkpoints are acceptable. - PR description warns the docs should stay in draft until the ComfyUI
assets-api-implementationbranch is merged, but the docs themselves have no version-gate or "available in" callout. Anyone reading post-merge will assume the endpoints are live and hit 404s on older deployments. Related: COM-13971leaks an internal-only Notion ticket (same as #742). Drop or replace with a public link.
| include_tags?: string[]; | ||
| exclude_tags?: string[]; | ||
| name_contains?: string; | ||
| sort?: "name" | "created_at" | "size"; |
There was a problem hiding this comment.
TS sort enum drops updated_at, contradicting the Python docstring (line 213) and the parameter table in comms_routes.mdx (line 72) — both of which list four values.
A TS user passing sort: "updated_at" (a value the prose presents as supported) gets a compile error. Either it's supported (and TS is wrong) or it isn't (and Python + the OSS-side table are wrong) — pick one and align all three.
- sort?: "name" | "created_at" | "size";
+ sort?: "name" | "created_at" | "updated_at" | "size";| async function addAssetTags(assetId: string, tags: string[]): Promise<void> { | ||
| const response = await fetch(`${BASE_URL}/api/assets/${assetId}/tags`, { | ||
| method: "POST", | ||
| headers: getHeaders(), | ||
| body: JSON.stringify({ tags }), | ||
| }); | ||
| if (!response.ok) throw new Error(`HTTP ${response.status}`); | ||
| } | ||
|
|
||
| async function removeAssetTags(assetId: string, tags: string[]): Promise<void> { | ||
| const response = await fetch(`${BASE_URL}/api/assets/${assetId}/tags`, { | ||
| method: "DELETE", | ||
| headers: getHeaders(), | ||
| body: JSON.stringify({ tags }), | ||
| }); | ||
| if (!response.ok) throw new Error(`HTTP ${response.status}`); | ||
| } |
There was a problem hiding this comment.
TS addAssetTags / removeAssetTags are typed Promise<void>, but the Python equivalents (lines 412, 422) return response.json() and declare -> dict.
Same endpoint, two response shapes — one of them has to be wrong. If the server returns a body (e.g. the updated tag list, or the asset record), the TS callers silently discard it; if it doesn't, the Python callers hit JSONDecodeError on empty responses. The fix depends on what the endpoint actually returns; align all four functions (TS + Python, add + remove) to match.
The curl examples (lines 379-388) don't show response bodies either, which makes this contradiction harder to catch from the docs alone.
| "size_bytes": 102400, | ||
| "mime_type": "image/png", | ||
| "tags": ["output", "image"], | ||
| "created_at": "2024-01-29T12:00:00Z", |
There was a problem hiding this comment.
Stale example timestamp on a net-new doc.
"2024-01-29T12:00:00Z" is roughly two years before this PR ships — a reader who notices will assume the example is copy-pasted from a much older doc and may distrust the rest. Cheap fix: bump to a current ISO-8601 timestamp, or use a stable placeholder like "<created_at-iso8601>".
| "mime_type": "image/png", | ||
| "tags": ["output", "image"], | ||
| "created_at": "2024-01-29T12:00:00Z", | ||
| "preview_url": "/api/assets/asset-uuid/content" |
There was a problem hiding this comment.
preview_url semantics aren't explained, and the field name is misleading without that context.
The example value "/api/assets/asset-uuid/content" (where the UUID matches id) is actually correct per the API contract: the API uses preview_id to designate a separate preview asset, and "if not provided, images will use their own ID as preview" (paraphrased from the spec). So preview_url for an asset without an explicit preview points at its own full content URL.
The issue is that the docs don't say any of this. A reader who treats preview_url as a thumbnail (the name strongly implies it) and uses it as an <img> source will:
- Render fine for small images.
- Hit timeouts / huge memory for video, audio, and especially model checkpoints (multi-GB content is not previewable).
Suggested doc fix on this row:
preview_urlis the URL of whatever asset is configured as this asset's preview (viapreview_id). For image assets without a separate preview, this defaults to the asset's own content URL — i.e. the full file, not a thumbnail. Don't use this as an<img>source for non-image asset types.
A proper thumbnail endpoint is a separate API question (out of scope for this docs PR).
2 participants
Summary
Adds comprehensive documentation for the Assets API (
/api/assets) as the recommended approach for file management instead of legacy/api/upload/*and/api/viewendpoints.Changes
GET /api/assets- List assets with tag/name/metadata filteringPOST /api/assets- Upload assets with tags and metadataGET /api/assets/{id}- Get asset detailsPOST/DELETE /api/assets/{id}/tags- Manage asset tagsDELETE /api/assets/{id}- Delete assets/api/upload/*section as legacy with recommendation to use Assets APINote
This PR should be kept as draft until the ComfyUI
assets-api-implementationbranch is merged.Related
Notion ticket: COM-13971