mirror of
https://github.com/comfyanonymous/ComfyUI.git
synced 2026-06-28 02:39:26 +08:00
7073a93653
* [Partner Nodes] feat: add Krea 2 Medium Turbo model (#14280)
* [Partner Nodes] feat: add seed input to Flux Erase node (#14283)
Signed-off-by: bigcat88 <bigcat88@icloud.com>
* chore: update workflow templates to v0.9.98 (#14284)
* Bump comfyui-frontend-package to 1.45.15 (#14265)
* Fix ideogram if model dtype gets set to fp8. (#14291)
* Consolidate audio nodes into SaveAudioAdvanced node (CORE-202) (#13871)
* Enable cfg1 optimization for DualModelGuider with CFGGuider (#14290)
* Enable cfg1 optimization for DualModelGuider
* Fix CFG Override tooltip
* Fix interoperation with external source of pinned memory pressure (#14252)
* mm: split off registration helper to doer and headroom calc
* pinned_memory: implement registration comfy side
Move away from Aimdo buffer registrations which seem fraught with
danger and do it comfy side. Just start with the basic move.
* pinned_memory: do registrations as portable memory
* pinned_memory: discard async errors on registration fail
Like the good ol days.
* pinned_memory: implement abs shortfall retry
If pinned registration happens to fail despite the previous budget
ensures, consider the allocation shortfall, ensure it again, and
try again. This allows comfy pins to interoperate with other software
that might be doing substantive pinning.
* aimdo 049 (#14300)
* [Partner Nodes] feat: add new Gemini text node (#14299)
* [Partner Nodes] feat: add temperature and top_p to NanoBanan node (#14305)
* feat: add PreviewGaussianSplat + PreviewPointCloud nodes (#14194)
* Update AMD portable readme. (#14303)
* BE-1172 fix(3d): save Preview3DAdvanced / PreviewGaussianSplat / PreviewPointCloud to temp/, rename viewport input (#14294)
* feat(3d): reorder Preview3DAdvanced / PreviewGaussianSplat / PreviewPointCloud inputs and outputs (#14308)
* Update line endings check to ignore .ci files. (#14319)
* Use windows line endings for windows portable readmes. (#14334)
* Add SeedVR2 support (CORE-6) (#14110)
* chore: update embedded docs to v0.5.3 (#14350)
* Add Color primitive (#14260)
* Improve ResolutionSelector (#14309)
* feat(assets): extract image dimensions at ingest and emit on asset responses (#13991)
* feat(assets): extract image dimensions at ingest and emit on asset responses
Image assets now carry width/height under the existing `metadata` field on
asset responses, shaped as `{"kind": "image", "width": W, "height": H}`.
This lets consumers get original dimensions (e.g. for clients that render
server-side thumbnails and can't recover them from naturalWidth/Height)
without an extra round-trip.
Dimensions are written to AssetReference.system_metadata across three
ingest paths:
- Direct file ingest (upload, in-place registration): Pillow reads the
image header right after hashing, while the file is still in OS page
cache. Non-image MIME types are skipped without touching the file.
- From-hash registration: this path never reads the file bytes, so
dimensions are best-effort copied from any prior sibling reference of
the same asset that already carries kind=image metadata. Missing
siblings, non-image siblings, or absent dimension keys leave the new
reference's metadata unchanged.
- Scanner enrichment: extends the existing system_metadata write in
enrich_asset so scanner-registered images get the same treatment as
uploaded ones.
Existing system_metadata keys (e.g. safetensors fields written by the
enricher, download provenance) are preserved through merge. Existing
assets ingested before this change retain their current metadata — no
automatic backfill in this PR.
Tests cover image emission, non-image no-op, merge preservation, and the
from-hash sibling back-fill (including the no-sibling and non-image-sibling
cases).
* fix(assets): validate sibling dimensions before backfilling
Per CodeRabbit review on #13991: the previous loop accepted any sibling
with `kind == "image"` and copied whichever dimension keys happened to
be present, then returned. A partial sibling (kind set but missing or
invalid width/height) could persist incomplete metadata onto the new
reference even when a later sibling had valid dimensions.
Now we validate that the sibling has both width and height as positive
integers before adopting its dimensions, and continue scanning to the
next sibling otherwise.
* fix(assets): reject booleans in sibling dimension validation (use type-is)
Per CodeRabbit follow-up on #13991: bool is a subclass of int in Python,
so isinstance(True, int) is True. The previous strict-int gate would
have accepted width=True (truthy + > 0) as a valid dimension.
Realistic occurrence is low (extract_image_dimensions returns proper
ints, JSON doesn't serialize bools as numbers), but the validation gate
exists for defense-in-depth so it should be actually strict.
---------
Co-authored-by: guill <jacob.e.segal@gmail.com>
* Revert "Add SeedVR2 support (CORE-6) (#14110)" (#14359)
This reverts commit 7863cf0e53.
* chore(openapi): sync shared API contract from cloud@5273c30 (#14266)
* fix: Add back apply_rotary_emb for Qwen Image (#14364)
* Allow custom templates with Ideogram4 TE (#14374)
* main/server: Add --debug-hang (#14371)
Add an option to debug a hang with ctrl-C, dumping the backtraces to
see where its stuck or slow.
* Add LoRA key mapping for LTXV/LTXAV models (#14349)
* feat: Add model support for SCAIL-2 (#14373)
* initial SCAIL2 support
* Move bg_removal_model input socket to first position for nicer display (#14353)
* mm: dont reset cast buffers in cleanup_models_gc() (#14372)
cleanup_models_gc can be called once per load_models_gpu via
free_memory, which in turn can de-activate an active model via
this reset_cast_buffers.
cleanup_models_gc() could also come via obscure garbage collector
paths so limit reset_cast_buffers to the post-node callsite instead.
* Ensure conditions are not trainable to avoid bugs (#14368)
* feat: Add Bernini-R model support (Wan video) (CORE-279) (#14216)
* Depth anything 3 (Core-135) (#13853)
Co-authored-by: Alexis Rolland <alexisrolland@hotmail.com>
* Always enable cuda malloc on cu130 and higher. (#14381)
* chore(openapi): sync shared API contract from cloud@ca12913 (#14367)
* [Trainer/bug] Ensure model is not inference mode (CORE-72) (#13400)
* Ensure model is not inference mode
* force clone inside training mode to avoid inference tensor
* Allow force deepcopy for model patcher
* chore(assets): drop vestigial tags.tag_type column (#14248)
tag_type was always "user" in practice — no code path ever set it to anything
else (no system/seeded classification was wired up) and nothing queried it. The
column, its ix_tags_tag_type index, and the TagUsage.type API field were dead
weight, so they're removed. Adds alembic migration 0004 to drop the column and
index.
Verified: asset-seeder tests pass; migration applies cleanly on a fresh SQLite
(tags retains only name; tag_type column + index dropped).
Co-authored-by: guill <jacob.e.segal@gmail.com>
* feat(assets): cursor-based pagination on GET /api/assets (#14014)
* spec(assets): add cursor pagination params to GET /api/assets
Add 'after' query param and 'next_cursor' response field for keyset
pagination. Matches the cloud Go implementation (BE-893) so frontend
sees a unified contract across runtimes. Offset/limit remain as a
deprecated fallback.
* feat(assets): add cursor encode/decode helpers for keyset pagination
Port of cloud common/pagination/cursor.go. Wire format is base64url of
{"s", "v", "id"} JSON; times are Unix microseconds UTC to match
PostgreSQL timestamp precision.
Includes a byte-identity fixture pinned against the cloud Go wire
format so cross-runtime FE pagination can't silently drift.
* feat(assets): thread cursor through schemas, service, and query layer
list_assets_page accepts an opaque 'after' cursor and returns
next_cursor when more pages are available. The query applies a keyset
WHERE clause and a secondary ORDER BY id for deterministic tiebreak.
Cursor sort field is validated against the request sort, and a
last_access_time sort (OSS-only) falls back to offset/limit. Offset is
ignored whenever a cursor is supplied.
* feat(assets): wire cursor pagination through GET /api/assets handler
Adds integration tests for: full cursor walk, invalid-cursor 400,
sort/cursor mismatch 400, cursor-wins-over-offset, absent next_cursor
when no more results, and pagination stability across deletes.
* fix(assets): address cursor-review verified findings
- Mint next_cursor on every cursor-supported sort, not only when 'after'
was supplied. A first request (no 'after') previously returned
next_cursor=None, leaving cursor mode unreachable from a clean start.
- Over-fetch limit+1 so an exactly-full terminal page doesn't mint a
spurious cursor pointing at a phantom next page.
- Map crafted out-of-range microsecond cursors (OverflowError / OSError
in datetime construction) to 400 INVALID_CURSOR instead of leaking 500.
- Bump MAX_CURSOR_VALUE_LENGTH 256 -> 512 to match the AssetReference
name column max; without this, a long-named asset minted a cursor the
same server then refused on the next request. Cross-runtime byte
identity with cloud is unaffected because no cloud cursor ever carries
a value > 256 (cloud schema doesn't permit it).
- Return None from _encode_next_cursor when the boundary row carries a
NULL sort value (e.g. an Asset without size_bytes backfilled), instead
of silently encoding 0 and mis-positioning the keyset.
- Fix schemas_in.py comment so it matches actual handler behavior
(last_access_time + 'after' raises 400, does not fall back).
- Add AssetsApiError schema + 400 response to GET /api/assets in
openapi.yaml so generated clients know the INVALID_CURSOR envelope.
- Extend integration coverage: first-page mint, exact-multiple terminal
page, cursor walks for created_at/updated_at/size sorts, datetime
overflow surfaces as 400 not 500.
- Add unit coverage for datetime overflow and 512-char round-trip.
* feat(assets): bind cursor to sort order + Go-compat JSON escaping
Address three needs-judgment items from the cursor-review judge synthesis:
1. Cursor wire format now includes an "o" key carrying the sort
direction ("asc" / "desc") it was minted under. A request that
replays the cursor with a flipped `order` parameter is rejected
with 400 INVALID_CURSOR instead of silently walking the wrong
direction. Legacy cursors without "o" still decode (the binding
is best-effort until cloud mirrors the field — follow-up filed
separately).
2. JSON serialization now escapes `<`, `>`, `&`, U+2028, U+2029
to mirror Go's default `json.Marshal` behavior. Without this, an
asset name containing those characters produced different bytes on
Python vs cloud Go. The escaped form is what both runtimes emit.
3. Add direct query-layer tests for the keyset tiebreaker — the secondary
ORDER BY id branch was previously unexercised. Two scenarios: all
rows share a primary sort value, and mixed ties straddle page
boundaries. Both assert no row is dropped or duplicated across the
walk.
Wire-format note: Python cursors now differ from current cloud cursors
by exactly the "o" key. Cloud follow-up will bring the two back into
byte alignment.
* fix(assets): address bot review comments
- Soften offset param prose: it's not deprecated, just not preferred for
sequential walks. Random-access UIs (jump-to-page, item count displays)
legitimately still want offset, so dropping the 'deprecated' framing
rather than promoting it to a machine-readable deprecated:true flag.
- Add explicit HTTP status assertions before every json() / next_cursor
read in test_list_cursor.py so a failing request surfaces as an HTTP
error instead of a confusing KeyError on a 4xx/5xx body.
* feat(assets): require cursor o field, drop legacy permissive path
Cursor pagination hasn't shipped on either runtime yet — this PR is
still draft and cloud's mirror is just behind it — so there are no
legacy no-o cursors in the wild. Make o mandatory from day one
rather than landing permissive and tightening later.
decode_cursor now rejects any payload without o (or with a non-string
o) as malformed. CursorPayload.order becomes a required str. Tests
that constructed CursorPayload directly now pass order="desc";
test_legacy_cursor_without_order_accepted flips to
test_cursor_without_order_rejected.
* chore(assets): drop cross-repo prose from cursor comments
Strip prose references to sibling Go implementations and external
ticket IDs from cursor.py, the cursor tests, the keyset integration
tests, asset_management's sort-field comment, and the legacy
prompt_id alias comment. Pure docstring/comment scrub — no behavior
or wire-format changes. x-runtime: [cloud] field annotations in
openapi.yaml are unchanged; those are the spec's structural
cross-runtime convention, not internal references.
* test(assets): include 'o' in microsecond-boundary cursor payload
The boundary test was building a cursor without the required `o` key, so
decode failed on the missing-order branch before reaching the µs-overflow
path the test is asserting. Both paths return 400 INVALID_CURSOR so the
assertion passed for the wrong reason. Add `o` to the payload and matching
`order=` to the request so the decode reaches the intended branch.
* fix(assets): address ultrareview findings on cursor pagination
Six fact-checked findings from the multi-model review pass:
- Encoder/decoder length asymmetry: encode_cursor now rejects empty id,
oversized id (>128), oversized value (>512), and invalid order tokens
symmetrically with decode_cursor. Prevents the same server from minting
a cursor it then 400s on the next request (e.g. a filesystem-scanned
asset name >512 chars). The bad-order path now raises InvalidCursorError
(still subclasses ValueError) so route-layer handling stays uniform.
- Raw U+2028/U+2029 in cursor.py source: ripgrep treated those lines as
line-terminators, confirming the bytes were the actual separators. Any
editor save / autoformat / git tooling that normalizes invisibles would
silently break the encoder. Replaced with explicit
/
Python escape sequences.
- set(seen) == set(names) hid ordering regressions: a cursor walk that
dropped a row at a page boundary or returned duplicates could pass.
Reworked the assertion to (1) reject duplicates, (2) require full
coverage, and (3) assert strict positional order for size sort, the
only field with a clock-independent ordering.
- Flaky time.sleep(0.05) between inserts: Windows CI clock resolution is
~15ms, so back-to-back inserts under load could collide and exercise
the tiebreaker instead of the documented path. Removed the sleep and
let the strengthened assertion above carry coverage / no-duplicates,
with size sort carrying strict order.
- Cursor error envelope diverged from the rest of routes.py: cursor 400s
emitted {error: {code, message}} while every other 400 in the file
emits {error: {code, message, details}} via _build_error_response.
Switched to _build_error_response and added the details field to the
AssetsApiError schema in openapi.yaml.
- "Byte-identity fixtures" only checked substring containment, defeating
the test class's stated purpose of pinning the wire format. Switched
to exact-bytes equality against an inline expected payload string per
fixture, so any whitespace / key-order / escape drift fails loudly.
Also dropped Go / json.Marshal references from docstrings — the byte
format is the contract, not the runtime that mints it.
* fix(assets): cap cursors by encoded wire size, not just char count
Char-count guards on value/id can still let multibyte or escape-heavy
inputs blow past MAX_ENCODED_CURSOR_LENGTH once UTF-8 + escape expansion
+ base64url runs. A 512-character name of 'é' (2 bytes UTF-8) or '<'
(serializes to the 6-byte '<' escape) passes the char check, mints
a ~1500-byte cursor, then 400s when handed back on the next request.
Compute the final encoded form and reject it before returning if it
exceeds the wire cap. Adds regression tests for both inflation paths.
* refactor(assets): extract cursor JSON escaping helper; size wire cap above per-field caps
Addresses review feedback on cursor.py:
- Extract the inline escape chain into _apply_wire_compatible_json_escapes()
with a comment pinning it to the wire format's escape set, so the parity
intent is explicit rather than reading as an ad-hoc transform.
- Raise MAX_ENCODED_CURSOR_LENGTH to 8192 (comfortably above the ~5.2KB
worst-case the per-field caps can produce) and drop the mint-time length
guard. Encoder/decoder symmetry now holds by construction: the encoder
can't produce a cursor the decode path rejects, so there is no confusing
user-visible 'cursor too long' failure at mint time.
- Rewrite the two over-wire-cap tests to assert worst-case multibyte and
escape-heavy values mint and round-trip, instead of being rejected.
* refactor(assets): drop cross-runtime cursor escaping; cursors are opaque
The custom JSON escaping of <, >, &, U+2028, and U+2029 existed only to
keep the encoded cursor byte-identical with the Cloud implementation of
the same payload format. Cursors are opaque tokens, so byte-level
compatibility across implementations is not needed — plain json.dumps
output is sufficient. Remove the escaping helper and the byte-identity
test fixtures that pinned the wire format; keep round-trip coverage for
the affected characters.
---------
Co-authored-by: guill <jacob.e.segal@gmail.com>
* fix(assets): remove unused delete_content param from deleteAsset (#14241)
* fix(assets): remove unused delete_content param from deleteAsset
The delete_content query param on DELETE /api/assets/{id} was introduced
in #12125 and had its default flipped to false in #12621. In practice no
client sends it: the frontend issues a bare DELETE /assets/{id}, so every
real caller already gets the default soft-delete (the reference is hidden,
content preserved). The only thing that set delete_content=true was this
repo's own test teardown.
Remove the param from the route and the OpenAPI spec so the contract
matches what clients actually use (and lines up with the cloud surface).
The route now always soft-deletes. The underlying delete_asset_reference
helper keeps its delete_content_if_orphan option, so orphan reclamation
remains available internally for a future GC path — it's just no longer
exposed on the public endpoint. Tests that used delete_content=true for
hard cleanup now soft-delete; test_delete_upon_reference_count asserts
content preservation instead of orphan removal.
* test/docs: address review on deleteAsset delete_content removal
- Rename test_delete_upon_reference_count ->
test_soft_delete_preserves_asset_identity_across_references; the old name
implied last-ref cleanup, but it now verifies the opposite (soft delete
preserves identity across references).
- Strengthen the re-association assertion: also check asset_hash == src_hash
so it proves content reuse rather than relying on the now-tautological
created_new is False.
- Document delete_asset_reference: the orphan-reclamation branch is
intentionally internal-only; the public endpoint always soft-deletes.
- Normalize the soft-delete comment phrasing.
* test(assets): make seed content unique per test for isolation
Removing the delete_content param means delete is always a soft delete, so
content created by one test now survives into the next. The suite had been
relying on hard-delete teardown for isolation, so shared fixed-content
fixtures started colliding: seeded_asset (b"A"*4096) and
make_asset_bytes (deterministic on name) produced the same hash every test,
so the second seed deduped to the surviving asset and returned 200 instead
of 201, cascading into ~14 failures/errors.
Salt both fixtures with a per-test uuid so each test creates fresh content
(created_new True, 201), while keeping content deterministic within a test
(same name/size -> same bytes) and preserving exact byte length so size-based
list/sort assertions are unaffected.
* main: force cudnn.benchmark to false (#14390)
Some custom nodes try to set this true globally. It messes with dynamic
VRAM with one-off spikes that can OOM but this is also very high risk
for windows where such allocations might get serviced by shared memory
fallback.
Trump it.
* feat(assets): add job_ids filter to GET /api/assets (#13998)
* feat(assets): add job_ids filter to GET /api/assets
Mirrors the existing cloud `job_ids` query param on the local Python server:
clients can pass a comma-separated list (or repeated query params) of UUIDs
to filter assets by their associated job.
The `AssetReference.job_id` column already exists, so no migration is
needed — this just plumbs the filter through schema → service → query.
Marks the parameter as available in both runtimes by dropping the
`[cloud-only]` description prefix and the `x-runtime: [cloud]` tag from
the OpenAPI spec, per the OSS field-drift convention (absent runtime tag
= populated by both local and cloud).
* fix(assets): tighten job_ids — array schema, max_length, narrow except
From cursor-reviews on the parent commit:
- OpenAPI: declare job_ids as `type: array, items: string format: uuid`
with `style: form, explode: true` so it matches the documented
contract (and matches sibling include_tags/exclude_tags shape).
Description now states both accepted shapes explicitly.
- Schema: cap `job_ids` at 500 entries (max_length on the Pydantic
field) so a client can't splice an unbounded list into the IN clauses.
- Schema: drop `AttributeError` from the except — `raw` only contains
`str` items by construction, so `uuid.UUID(<str>)` raises `ValueError`
exclusively; the second clause was dead code.
* fix(assets): tighten job_ids validator + add schema-level tests
Aligns with the parallel hardening from draft PR #13848 (now closed as
a duplicate). The validator now:
- Raises ValueError on non-string list items (was: silently dropped).
- Raises ValueError on non-string / non-list top-level values like dict
or int (was: silently passed through to Pydantic's downstream coercion).
Adds tests-unit/assets_test/queries/test_list_assets_query.py covering
the validator end-to-end: CSV canonicalization, dedup order, default
empty, invalid UUID, non-string list item, non-string non-list value,
and the max_length=500 boundary.
* feat(prompt): enforce canonical UUID prompt_id at job creation
POST /prompt previously accepted any client-supplied prompt_id verbatim,
str()-coercing even non-strings, and minting the literal job id "None"
for an explicit JSON null. The new GET /api/assets job_ids filter matches
stored job ids as canonical UUIDs exactly, so a non-UUID id minted a job
whose assets could never be filtered.
- validate_job_id (comfy_execution/jobs.py): requires a string in the
canonical lowercase hyphenated UUID form; raises ValueError otherwise,
including parseable-but-non-canonical spellings (uppercase, braced, URN,
bare hex), which would otherwise be silently rewritten and then miss
every exact-match lookup downstream (history keys, websocket
correlation, /interrupt, the assets job_ids filter).
- POST /prompt: absent or null prompt_id means the server mints uuid4;
invalid means 400 invalid_prompt_id on the standard error envelope.
- openapi.yaml: document the request-side prompt_id (format uuid,
nullable) on PromptRequest.
- tests: unit matrix for validate_job_id; integration tests against the
booted server covering rejection, acceptance, and null handling.
---------
Co-authored-by: guill <jacob.e.segal@gmail.com>
* feat(assets): include asset id in executed WebSocket message (#13862)
* feat(assets): enrich executed WS message with asset metadata
When --enable-assets is set, each file-type output entry in the
`executed` WebSocket message now includes id, name, asset_hash, size,
and mime_type — matching the shape already returned by /upload/image.
The enrichment lives in comfy_execution/asset_enrichment.py (no torch
dependency) and is called from both send sites in execution.py: freshly
executed nodes register the file inline via register_file_in_place;
cached node re-sends look up the existing AssetReference by file path
to avoid re-hashing. Errors are caught per-entry so a failure never
blocks the WS message from sending.
* fix(assets): inject only id in executed WS message per Asset Identity RFC
Per the Asset Identity RFC, the executed WebSocket payload should carry
id alone — hash is already encoded in the filename, and name/preview_url/
size belong behind GET /api/assets/{id} rather than being pushed eagerly.
Simplifies the DB lookup path: we only need ref.id, so the asset.hash
null-check is no longer required as a fallback trigger.
* fix(assets): reject path traversal when resolving output abs_path
Subfolder/filename were joined and absolutized without containment check,
so '..' segments or an absolute filename could escape the type's base
directory and register an unrelated on-disk file as an asset.
Add commonpath-based containment check; skip enrichment (warn, leave
entry unchanged) when the resolved path escapes base. Catches ValueError
from cross-drive paths on Windows.
* docs(assets): drop Asset Identity RFC reference from docstring
* docs(assets): trim docstring to what enrichment does, not what it doesn't
* test(assets): use real platform paths so containment check works on Windows
The previous test setup patched os.path.abspath to identity and used a
POSIX-style '/output' base, which collided with Windows path separators
in os.path.commonpath. Drop the abspath/join patches and use a real
tempdir-rooted base so the containment check runs against actual
platform paths.
* refactor(assets): enrich at output-processing time, not in the WS send path
Per review: enrichment lived inside the client_id-guarded send sites, so a
headless run (no websocket client) never registered assets at all, and
ui_outputs/history stored the un-enriched entries.
Now output_ui is enriched once, right after the node produces it and before
it is stored in ui_outputs — so registration happens regardless of connected
clients, and the asset id flows into history and the execution cache for
free. _send_cached_ui re-sends the stored (already-enriched) dict verbatim,
which lets the DB-lookup-by-path fallback be deleted: every enrichment is
now a fresh output, and register_file_in_place re-hashes on upsert so an
overwritten path can never carry a stale id.
* revert(assets): drop job_ids filter from GET /api/assets (#14408)
The job_ids query filter added in #13998 has no live consumer: the
frontend Generated tab kept sourcing from GET /jobs, and the cloud side
removed its equivalent filter from the shared asset spec. Carrying it on
the local server only re-introduces Core<->Cloud drift on the shared
contract, so remove it to match.
Removed: the job_ids field + validator on ListAssetsQuery, the IN(...)
clauses in list_references_page, the service/route passthrough, and the
filter-only tests.
Kept: the canonical-UUID prompt_id enforcement at job creation (also
landed in #13998). It stands on its own -- job ids are matched verbatim
by history keys, websocket correlation, and /interrupt -- and cloud
inherits it by running core for execution, so no divergence is created.
* chore(openapi): sync shared API contract from cloud@e3c52ad (#14406)
* I don't think this actually works anymore. (#14403)
* ops: tolerate already force casted dynamic weight (#14410)
Some custom nodes .to weights completely out of load context which
can wreak havoc if its for a model that is not active. Detect this
condition and just let it fall-through to the non-dynamic loader
straight up.
---------
Signed-off-by: bigcat88 <bigcat88@icloud.com>
Co-authored-by: Alexander Piskun <13381981+bigcat88@users.noreply.github.com>
Co-authored-by: Daxiong (Lin) <contact@comfyui-wiki.com>
Co-authored-by: Comfy Org PR Bot <snomiao+comfy-pr@gmail.com>
Co-authored-by: comfyanonymous <121283862+comfyanonymous@users.noreply.github.com>
Co-authored-by: Alexis Rolland <alexisrolland@hotmail.com>
Co-authored-by: Jukka Seppänen <40791699+kijai@users.noreply.github.com>
Co-authored-by: rattus <46076784+rattus128@users.noreply.github.com>
Co-authored-by: Terry Jia <terryjia88@gmail.com>
Co-authored-by: John Pollock <pollockjj@users.noreply.github.com>
Co-authored-by: Silver <65376327+silveroxides@users.noreply.github.com>
Co-authored-by: Matt Miller <mattmiller@comfy.org>
Co-authored-by: guill <jacob.e.segal@gmail.com>
Co-authored-by: kelseyee <971704395@qq.com>
Co-authored-by: Kohaku-Blueleaf <59680068+KohakuBlueleaf@users.noreply.github.com>
Co-authored-by: Talmaj <Talmaj@users.noreply.github.com>
4888 lines
198 KiB
YAML
4888 lines
198 KiB
YAML
components:
|
|
schemas:
|
|
Asset:
|
|
description: Represents a user-owned asset (image, video, or other generated output).
|
|
properties:
|
|
created_at:
|
|
description: Timestamp when the asset was created
|
|
format: date-time
|
|
type: string
|
|
display_name:
|
|
description: Display name of the asset. Mirrors name for backwards compatibility.
|
|
nullable: true
|
|
type: string
|
|
file_path:
|
|
description: Relative path in global-namespace-root form (e.g. "models/checkpoints/flux.safetensors")
|
|
nullable: true
|
|
type: string
|
|
hash:
|
|
description: Blake3 hash of the asset content.
|
|
pattern: ^blake3:[a-f0-9]{64}$
|
|
type: string
|
|
id:
|
|
description: Unique identifier for the asset
|
|
format: uuid
|
|
type: string
|
|
is_immutable:
|
|
description: Whether this asset is immutable (cannot be modified or deleted)
|
|
type: boolean
|
|
job_id:
|
|
description: ID of the job that created this asset, if available
|
|
format: uuid
|
|
nullable: true
|
|
type: string
|
|
last_access_time:
|
|
description: Timestamp when the asset was last accessed
|
|
format: date-time
|
|
type: string
|
|
metadata:
|
|
additionalProperties: true
|
|
description: System-managed metadata from download sources (HuggingFace, CivitAI, etc.) - read-only, not user-modifiable
|
|
readOnly: true
|
|
type: object
|
|
mime_type:
|
|
description: MIME type of the asset
|
|
type: string
|
|
name:
|
|
description: Name of the asset file
|
|
type: string
|
|
preview_id:
|
|
description: ID of the preview asset if available
|
|
format: uuid
|
|
nullable: true
|
|
type: string
|
|
preview_url:
|
|
description: URL for asset preview/thumbnail
|
|
format: uri
|
|
type: string
|
|
size:
|
|
description: Size of the asset in bytes
|
|
format: int64
|
|
type: integer
|
|
tags:
|
|
description: Tags associated with the asset
|
|
items:
|
|
type: string
|
|
type: array
|
|
updated_at:
|
|
description: Timestamp when the asset was last updated
|
|
format: date-time
|
|
type: string
|
|
user_metadata:
|
|
additionalProperties: true
|
|
description: Custom user metadata for the asset
|
|
type: object
|
|
required:
|
|
- id
|
|
- name
|
|
- created_at
|
|
- updated_at
|
|
type: object
|
|
AssetCreated:
|
|
allOf:
|
|
- $ref: '#/components/schemas/Asset'
|
|
- properties:
|
|
created_new:
|
|
description: Whether this was a new asset creation (true) or returned existing (false)
|
|
type: boolean
|
|
required:
|
|
- created_new
|
|
type: object
|
|
description: Response returned when a new asset is successfully created.
|
|
AssetInfo:
|
|
description: Lightweight asset reference used in workflow publishing payloads.
|
|
properties:
|
|
id:
|
|
description: Asset identifier.
|
|
type: string
|
|
in_library:
|
|
description: Whether the caller already owns this asset.
|
|
type: boolean
|
|
model:
|
|
description: Whether this asset is a model.
|
|
type: boolean
|
|
name:
|
|
type: string
|
|
preview_url:
|
|
description: Signed URL for previewing the asset.
|
|
type: string
|
|
public:
|
|
description: Whether this is a public (platform-provided) asset.
|
|
type: boolean
|
|
storage_url:
|
|
type: string
|
|
required:
|
|
- id
|
|
- name
|
|
- preview_url
|
|
- storage_url
|
|
- model
|
|
- public
|
|
- in_library
|
|
type: object
|
|
AssetTagHistogramResponse:
|
|
description: Histogram of tag counts used for refining asset search results.
|
|
properties:
|
|
tag_counts:
|
|
additionalProperties:
|
|
type: integer
|
|
description: Map of tag names to their occurrence counts on matching assets
|
|
example:
|
|
checkpoint: 32
|
|
lora: 193
|
|
vae: 6
|
|
type: object
|
|
required:
|
|
- tag_counts
|
|
type: object
|
|
AssetUpdated:
|
|
description: Response returned when an existing asset is successfully updated.
|
|
properties:
|
|
display_name:
|
|
description: Display name of the asset. Mirrors name for backwards compatibility.
|
|
nullable: true
|
|
type: string
|
|
file_path:
|
|
description: Relative path in global-namespace-root form (e.g. "models/checkpoints/flux.safetensors")
|
|
nullable: true
|
|
type: string
|
|
hash:
|
|
description: Blake3 hash of the asset content.
|
|
pattern: ^blake3:[a-f0-9]{64}$
|
|
type: string
|
|
id:
|
|
description: Asset ID
|
|
format: uuid
|
|
type: string
|
|
job_id:
|
|
description: ID of the job that created this asset, if available
|
|
format: uuid
|
|
nullable: true
|
|
type: string
|
|
mime_type:
|
|
description: Updated MIME type of the asset
|
|
type: string
|
|
name:
|
|
description: Updated name of the asset
|
|
type: string
|
|
tags:
|
|
description: Tags associated with the asset
|
|
items:
|
|
type: string
|
|
type: array
|
|
updated_at:
|
|
description: Timestamp of the update
|
|
format: date-time
|
|
type: string
|
|
user_metadata:
|
|
additionalProperties: true
|
|
description: Updated custom metadata
|
|
type: object
|
|
required:
|
|
- id
|
|
- updated_at
|
|
type: object
|
|
CreateWorkflowRequest:
|
|
description: Request body for creating a new saved workflow.
|
|
properties:
|
|
default_view:
|
|
description: Default view mode
|
|
enum:
|
|
- workflow
|
|
- app
|
|
type: string
|
|
description:
|
|
description: Description of the workflow
|
|
type: string
|
|
forked_from_workflow_id:
|
|
description: ID of the source workflow if forked
|
|
type: string
|
|
forked_from_workflow_version_id:
|
|
description: ID of the source workflow version if forked
|
|
type: string
|
|
name:
|
|
description: Display name for the workflow
|
|
type: string
|
|
workflow_json:
|
|
additionalProperties: true
|
|
description: The ComfyUI workflow JSON
|
|
type: object
|
|
required:
|
|
- workflow_json
|
|
type: object
|
|
CreateWorkflowVersionRequest:
|
|
description: Request body for creating a new version of a saved workflow.
|
|
properties:
|
|
base_version:
|
|
description: The version number this change is based on (for optimistic concurrency)
|
|
type: integer
|
|
workflow_json:
|
|
additionalProperties: true
|
|
description: The updated ComfyUI workflow JSON
|
|
type: object
|
|
required:
|
|
- base_version
|
|
- workflow_json
|
|
type: object
|
|
ErrorResponse:
|
|
description: Standard error response with a machine-readable code and human-readable message.
|
|
properties:
|
|
code:
|
|
type: string
|
|
details:
|
|
additionalProperties: true
|
|
description: Optional open object carrying structured, machine-readable context about the error (e.g. offending field names, validation specifics). Absent for most errors; consumers must not assume any particular shape.
|
|
type: object
|
|
message:
|
|
type: string
|
|
required:
|
|
- code
|
|
- message
|
|
type: object
|
|
ExecutionError:
|
|
description: Detailed execution error information from ComfyUI
|
|
properties:
|
|
current_inputs:
|
|
additionalProperties: true
|
|
description: Input values at time of failure (empty object if not available)
|
|
type: object
|
|
current_outputs:
|
|
additionalProperties: true
|
|
description: Output values at time of failure (empty object if not available)
|
|
type: object
|
|
exception_message:
|
|
description: Human-readable error message
|
|
type: string
|
|
exception_type:
|
|
description: Python exception type (e.g., "RuntimeError")
|
|
type: string
|
|
node_id:
|
|
description: ID of the node that failed
|
|
type: string
|
|
node_type:
|
|
description: Type name of the node (e.g., "KSampler")
|
|
type: string
|
|
traceback:
|
|
description: Array of traceback lines (empty array if not available)
|
|
items:
|
|
type: string
|
|
type: array
|
|
required:
|
|
- node_id
|
|
- node_type
|
|
- exception_message
|
|
- exception_type
|
|
- traceback
|
|
- current_inputs
|
|
- current_outputs
|
|
type: object
|
|
FeedbackRequest:
|
|
description: Request to submit user feedback
|
|
properties:
|
|
content:
|
|
description: The feedback content or message
|
|
type: string
|
|
metadata:
|
|
additionalProperties: true
|
|
description: Additional metadata about the feedback
|
|
type: object
|
|
rating:
|
|
description: User's rating of ComfyUI Cloud experience (1-5 stars)
|
|
maximum: 5
|
|
minimum: 1
|
|
type: integer
|
|
type:
|
|
description: Type of feedback being submitted
|
|
enum:
|
|
- missing_nodes
|
|
- general
|
|
- missing_models
|
|
type: string
|
|
required:
|
|
- type
|
|
type: object
|
|
FeedbackResponse:
|
|
description: Response after submitting feedback
|
|
type: object
|
|
ForkWorkflowRequest:
|
|
description: Request body for forking an existing workflow into the user's account.
|
|
properties:
|
|
name:
|
|
description: Name for the forked workflow
|
|
type: string
|
|
source_version:
|
|
description: Version number to fork from
|
|
type: integer
|
|
required:
|
|
- source_version
|
|
type: object
|
|
GetUserDataResponseFull:
|
|
description: List of user data file entries (each with path, size, and modification time) returned when full_info=true.
|
|
items:
|
|
$ref: '#/components/schemas/GetUserDataResponseFullFile'
|
|
type: array
|
|
GetUserDataResponseFullFile:
|
|
description: Individual file entry within a full user data response.
|
|
properties:
|
|
modified:
|
|
description: UNIX timestamp of the last modification in milliseconds.
|
|
format: int64
|
|
type: integer
|
|
path:
|
|
description: File name or path relative to the user directory.
|
|
type: string
|
|
size:
|
|
description: File size in bytes.
|
|
type: integer
|
|
type: object
|
|
GlobalSubgraphData:
|
|
description: Full data for a global subgraph blueprint
|
|
properties:
|
|
data:
|
|
description: The full subgraph JSON data as a string
|
|
type: string
|
|
info:
|
|
description: Additional information about the subgraph
|
|
properties:
|
|
node_pack:
|
|
description: The node pack/module that provides this subgraph
|
|
type: string
|
|
required:
|
|
- node_pack
|
|
type: object
|
|
name:
|
|
description: Display name of the subgraph blueprint
|
|
type: string
|
|
source:
|
|
description: Source type of the subgraph - "templates" for workflow templates or "custom_node" for custom node subgraphs
|
|
type: string
|
|
required:
|
|
- source
|
|
- name
|
|
- info
|
|
- data
|
|
type: object
|
|
GlobalSubgraphInfo:
|
|
description: Metadata for a global subgraph blueprint (without full data)
|
|
properties:
|
|
data:
|
|
description: The full subgraph JSON data (may be empty in list view)
|
|
type: string
|
|
info:
|
|
description: Additional information about the subgraph
|
|
properties:
|
|
node_pack:
|
|
description: The node pack/module that provides this subgraph
|
|
type: string
|
|
required:
|
|
- node_pack
|
|
type: object
|
|
name:
|
|
description: Display name of the subgraph blueprint
|
|
type: string
|
|
source:
|
|
description: Source type of the subgraph - "templates" for workflow templates or "custom_node" for custom node subgraphs
|
|
type: string
|
|
required:
|
|
- source
|
|
- name
|
|
- info
|
|
type: object
|
|
HistoryDetailEntry:
|
|
description: History entry with full prompt data
|
|
properties:
|
|
meta:
|
|
additionalProperties: true
|
|
description: Metadata about the execution and nodes
|
|
type: object
|
|
outputs:
|
|
additionalProperties: true
|
|
description: Output data from execution (generated images, files, etc.)
|
|
type: object
|
|
prompt:
|
|
description: Full prompt execution data
|
|
properties:
|
|
extra_data:
|
|
additionalProperties: true
|
|
description: Additional execution data
|
|
type: object
|
|
outputs_to_execute:
|
|
description: Output nodes to execute
|
|
items:
|
|
type: string
|
|
type: array
|
|
priority:
|
|
description: Execution priority
|
|
format: double
|
|
type: number
|
|
prompt:
|
|
additionalProperties: true
|
|
description: The workflow nodes
|
|
type: object
|
|
prompt_id:
|
|
description: The prompt ID
|
|
type: string
|
|
type: object
|
|
status:
|
|
additionalProperties: true
|
|
description: Execution status and timeline information
|
|
type: object
|
|
type: object
|
|
HistoryDetailResponse:
|
|
additionalProperties:
|
|
$ref: '#/components/schemas/HistoryDetailEntry'
|
|
description: |
|
|
Detailed execution history response for a specific prompt.
|
|
Returns a dictionary with prompt_id as key and full history data as value.
|
|
type: object
|
|
HistoryEntry:
|
|
description: History entry with prompt_id and execution data
|
|
properties:
|
|
create_time:
|
|
description: Job creation timestamp (Unix timestamp in milliseconds)
|
|
format: int64
|
|
type: integer
|
|
meta:
|
|
additionalProperties: true
|
|
description: Metadata about the execution and nodes
|
|
type: object
|
|
outputs:
|
|
additionalProperties: true
|
|
description: Output data from execution (generated images, files, etc.)
|
|
type: object
|
|
prompt:
|
|
description: Filtered prompt execution data (lightweight format)
|
|
properties:
|
|
extra_data:
|
|
additionalProperties: true
|
|
description: Additional execution data (workflow removed from extra_pnginfo)
|
|
type: object
|
|
priority:
|
|
description: Execution priority
|
|
format: double
|
|
type: number
|
|
prompt_id:
|
|
description: The prompt ID
|
|
type: string
|
|
type: object
|
|
prompt_id:
|
|
description: Unique identifier for this prompt execution
|
|
type: string
|
|
status:
|
|
additionalProperties: true
|
|
description: Execution status and timeline information
|
|
type: object
|
|
workflow_id:
|
|
description: UUID identifying the workflow graph definition
|
|
type: string
|
|
required:
|
|
- prompt_id
|
|
type: object
|
|
HistoryManageRequest:
|
|
additionalProperties: false
|
|
description: Request to manage history operations
|
|
properties:
|
|
clear:
|
|
description: If true, clear all history for the authenticated user
|
|
type: boolean
|
|
delete:
|
|
description: Array of job IDs to delete from history
|
|
items:
|
|
type: string
|
|
type: array
|
|
type: object
|
|
HistoryResponse:
|
|
description: |
|
|
Execution history response with history array.
|
|
Returns an object with a "history" key containing an array of history entries.
|
|
Each entry includes prompt_id as a property along with execution data.
|
|
properties:
|
|
history:
|
|
description: Array of history entries ordered by creation time (newest first)
|
|
items:
|
|
$ref: '#/components/schemas/HistoryEntry'
|
|
type: array
|
|
required:
|
|
- history
|
|
type: object
|
|
JobCancelResponse:
|
|
description: Response for POST /api/jobs/{job_id}/cancel. Returned on both fresh cancels and idempotent no-ops.
|
|
properties:
|
|
cancelled:
|
|
description: |
|
|
True when a cancel event was successfully dispatched by this call.
|
|
False when the job was already in a terminal or cancelling state,
|
|
in which case the call is a no-op (still 200 — idempotent).
|
|
type: boolean
|
|
required:
|
|
- cancelled
|
|
type: object
|
|
JobDetailResponse:
|
|
description: Full job details including workflow and outputs
|
|
properties:
|
|
create_time:
|
|
description: Job creation timestamp (Unix timestamp in milliseconds)
|
|
format: int64
|
|
type: integer
|
|
execution_error:
|
|
allOf:
|
|
- $ref: '#/components/schemas/ExecutionError'
|
|
description: Detailed execution error from ComfyUI (only for failed jobs with structured error data)
|
|
execution_meta:
|
|
additionalProperties: true
|
|
description: Node-level execution metadata (only for terminal states)
|
|
type: object
|
|
execution_status:
|
|
additionalProperties: true
|
|
description: ComfyUI execution status and timeline (only for terminal states)
|
|
type: object
|
|
id:
|
|
description: Unique job identifier
|
|
format: uuid
|
|
type: string
|
|
outputs:
|
|
additionalProperties: true
|
|
description: Full outputs object from ComfyUI (only for terminal states)
|
|
type: object
|
|
outputs_count:
|
|
description: Total number of output files (omitted for non-terminal states)
|
|
type: integer
|
|
preview_output:
|
|
additionalProperties: true
|
|
description: Primary preview output (only for terminal states)
|
|
type: object
|
|
status:
|
|
description: User-friendly job status
|
|
enum:
|
|
- pending
|
|
- in_progress
|
|
- completed
|
|
- failed
|
|
- cancelled
|
|
type: string
|
|
update_time:
|
|
description: Last update timestamp (Unix timestamp in milliseconds)
|
|
format: int64
|
|
type: integer
|
|
workflow:
|
|
additionalProperties: true
|
|
description: |
|
|
Full ComfyUI workflow (10-100KB, omitted if not available).
|
|
|
|
Sensitive credentials are redacted before the response is returned:
|
|
`extra_data.api_key_comfy_org`, when present, is replaced with the
|
|
literal string `"[REDACTED]"`. The field is preserved (not removed)
|
|
so existence checks still pass, but the value is not usable.
|
|
type: object
|
|
workflow_id:
|
|
description: UUID identifying the workflow graph definition
|
|
type: string
|
|
required:
|
|
- id
|
|
- status
|
|
- create_time
|
|
- update_time
|
|
type: object
|
|
JobEntry:
|
|
description: Lightweight job data for list views (workflow and full outputs excluded)
|
|
properties:
|
|
create_time:
|
|
description: Job creation timestamp (Unix timestamp in milliseconds)
|
|
format: int64
|
|
type: integer
|
|
execution_end_time:
|
|
description: Workflow execution completion timestamp (Unix milliseconds, only present for terminal states)
|
|
format: int64
|
|
type: integer
|
|
execution_error:
|
|
allOf:
|
|
- $ref: '#/components/schemas/ExecutionError'
|
|
description: Detailed execution error from ComfyUI (only for failed jobs with structured error data)
|
|
execution_start_time:
|
|
description: Workflow execution start timestamp (Unix milliseconds, only present for terminal states)
|
|
format: int64
|
|
type: integer
|
|
id:
|
|
description: Unique job identifier
|
|
format: uuid
|
|
type: string
|
|
outputs_count:
|
|
description: Total number of output files (omitted for non-terminal states)
|
|
type: integer
|
|
preview_output:
|
|
additionalProperties: true
|
|
description: Primary preview output (only present for terminal states)
|
|
type: object
|
|
status:
|
|
description: User-friendly job status
|
|
enum:
|
|
- pending
|
|
- in_progress
|
|
- completed
|
|
- failed
|
|
- cancelled
|
|
type: string
|
|
workflow_id:
|
|
description: UUID identifying the workflow graph definition
|
|
type: string
|
|
required:
|
|
- id
|
|
- status
|
|
- create_time
|
|
type: object
|
|
JobStatusResponse:
|
|
description: Job status information
|
|
properties:
|
|
assigned_inference:
|
|
description: The inference instance assigned to this job (if any)
|
|
nullable: true
|
|
type: string
|
|
created_at:
|
|
description: When the job was created
|
|
format: date-time
|
|
type: string
|
|
error_message:
|
|
description: Error message if the job failed
|
|
nullable: true
|
|
type: string
|
|
id:
|
|
description: The job ID
|
|
format: uuid
|
|
type: string
|
|
last_state_update:
|
|
description: When the job status was last changed
|
|
format: date-time
|
|
type: string
|
|
status:
|
|
description: Current job status
|
|
enum:
|
|
- waiting_to_dispatch
|
|
- pending
|
|
- in_progress
|
|
- completed
|
|
- error
|
|
- cancelled
|
|
type: string
|
|
updated_at:
|
|
description: When the job was last updated
|
|
format: date-time
|
|
type: string
|
|
required:
|
|
- id
|
|
- status
|
|
- created_at
|
|
- updated_at
|
|
type: object
|
|
JobsListResponse:
|
|
description: Paginated list of jobs for the authenticated user.
|
|
properties:
|
|
jobs:
|
|
description: Array of jobs ordered by specified sort field
|
|
items:
|
|
$ref: '#/components/schemas/JobEntry'
|
|
type: array
|
|
pagination:
|
|
$ref: '#/components/schemas/PaginationInfo'
|
|
required:
|
|
- jobs
|
|
- pagination
|
|
type: object
|
|
ListAssetsResponse:
|
|
description: Paginated list of assets belonging to the authenticated user.
|
|
properties:
|
|
assets:
|
|
description: List of assets matching the query
|
|
items:
|
|
$ref: '#/components/schemas/Asset'
|
|
type: array
|
|
has_more:
|
|
description: Whether more assets are available beyond this page
|
|
type: boolean
|
|
next_cursor:
|
|
description: |
|
|
Opaque cursor to pass as the `after` query parameter to fetch the
|
|
next page. Omitted from the response when there are no more results.
|
|
type: string
|
|
total:
|
|
description: Total number of assets matching the filters
|
|
type: integer
|
|
required:
|
|
- assets
|
|
- total
|
|
- has_more
|
|
type: object
|
|
ListTagsResponse:
|
|
description: Paginated list of available asset tags.
|
|
properties:
|
|
has_more:
|
|
description: Whether more tags are available
|
|
type: boolean
|
|
tags:
|
|
description: List of tags
|
|
items:
|
|
$ref: '#/components/schemas/TagInfo'
|
|
type: array
|
|
total:
|
|
description: Total number of tags
|
|
type: integer
|
|
required:
|
|
- tags
|
|
- total
|
|
- has_more
|
|
type: object
|
|
ModelFile:
|
|
description: Represents a model file with metadata
|
|
properties:
|
|
name:
|
|
description: The filename of the model
|
|
example: model.safetensors
|
|
type: string
|
|
pathIndex:
|
|
description: Index of the path where this model is located
|
|
example: 0
|
|
type: integer
|
|
required:
|
|
- name
|
|
- pathIndex
|
|
type: object
|
|
ModelFolder:
|
|
description: Represents a folder containing models
|
|
properties:
|
|
folders:
|
|
description: List of paths where models of this type are stored
|
|
example:
|
|
- checkpoints
|
|
items:
|
|
type: string
|
|
type: array
|
|
name:
|
|
description: The name of the model folder
|
|
example: checkpoints
|
|
type: string
|
|
required:
|
|
- name
|
|
- folders
|
|
type: object
|
|
NodeInfo:
|
|
description: Metadata describing a single ComfyUI node type and its inputs/outputs.
|
|
properties:
|
|
api_node:
|
|
description: Whether this is an API node
|
|
type: boolean
|
|
category:
|
|
description: Category of the node
|
|
type: string
|
|
deprecated:
|
|
description: Whether the node is deprecated
|
|
type: boolean
|
|
description:
|
|
description: Description of the node
|
|
type: string
|
|
display_name:
|
|
description: Display name of the node
|
|
type: string
|
|
experimental:
|
|
description: Whether the node is experimental
|
|
type: boolean
|
|
input:
|
|
additionalProperties: true
|
|
description: Input specifications for the node
|
|
type: object
|
|
input_order:
|
|
additionalProperties:
|
|
items:
|
|
type: string
|
|
type: array
|
|
description: Order of inputs for display
|
|
type: object
|
|
name:
|
|
description: Internal name of the node
|
|
type: string
|
|
output:
|
|
description: Output types of the node
|
|
items:
|
|
type: string
|
|
type: array
|
|
output_is_list:
|
|
description: Whether each output is a list
|
|
items:
|
|
type: boolean
|
|
type: array
|
|
output_name:
|
|
description: Names of the outputs
|
|
items:
|
|
type: string
|
|
type: array
|
|
output_node:
|
|
description: Whether this is an output node
|
|
type: boolean
|
|
output_tooltips:
|
|
description: Tooltips for outputs
|
|
items:
|
|
type: string
|
|
type: array
|
|
python_module:
|
|
description: Python module implementing the node
|
|
type: string
|
|
type: object
|
|
PaginationInfo:
|
|
description: |
|
|
Pagination metadata included in list responses. Supports both legacy
|
|
offset/limit pagination and cursor-based pagination. When cursor-based
|
|
pagination is used, `next_cursor` is the primary pagination token and
|
|
`offset`/`total` may be zero.
|
|
properties:
|
|
has_more:
|
|
description: Whether more items are available beyond this page
|
|
type: boolean
|
|
limit:
|
|
description: Items per page
|
|
minimum: 1
|
|
type: integer
|
|
next_cursor:
|
|
description: |
|
|
Opaque cursor for the next page. Pass this value as the `after`
|
|
query parameter on the next request. Empty or absent when there
|
|
are no more results.
|
|
type: string
|
|
offset:
|
|
deprecated: true
|
|
description: 'Current offset (0-based). Deprecated: use cursor-based pagination.'
|
|
minimum: 0
|
|
type: integer
|
|
total:
|
|
description: Total number of items matching filters (may be 0 when using cursor pagination)
|
|
minimum: 0
|
|
type: integer
|
|
required:
|
|
- offset
|
|
- limit
|
|
- total
|
|
- has_more
|
|
type: object
|
|
PromptErrorResponse:
|
|
additionalProperties: true
|
|
description: Error response for ComfyUI prompt execution.
|
|
type: object
|
|
PromptInfo:
|
|
description: Metadata about the currently running and queued prompts.
|
|
properties:
|
|
exec_info:
|
|
properties:
|
|
queue_remaining:
|
|
description: Number of items remaining in the queue
|
|
type: integer
|
|
type: object
|
|
type: object
|
|
PromptRequest:
|
|
description: Request body for submitting a ComfyUI workflow prompt for execution.
|
|
properties:
|
|
extra_data:
|
|
additionalProperties: true
|
|
description: Extra data to be associated with the prompt
|
|
type: object
|
|
front:
|
|
description: If true, adds the prompt to the front of the queue
|
|
type: boolean
|
|
number:
|
|
description: Priority number for the queue (lower numbers have higher priority)
|
|
type: number
|
|
partial_execution_targets:
|
|
description: List of node names to execute
|
|
items:
|
|
type: string
|
|
type: array
|
|
prompt:
|
|
additionalProperties: true
|
|
description: The workflow graph to execute
|
|
type: object
|
|
prompt_id:
|
|
description: Optional client-supplied job id. Must be a UUID in canonical lowercase hyphenated form; it is echoed back in the response. Omitted or null means the server generates one.
|
|
format: uuid
|
|
nullable: true
|
|
type: string
|
|
workflow_id:
|
|
description: UUID identifying the cloud workflow entity to associate with this job
|
|
type: string
|
|
workflow_version_id:
|
|
description: UUID identifying the workflow version to associate with this job
|
|
type: string
|
|
required:
|
|
- prompt
|
|
type: object
|
|
PromptResponse:
|
|
description: Response returned after successfully queuing a workflow prompt.
|
|
properties:
|
|
node_errors:
|
|
additionalProperties: true
|
|
description: Any errors in the nodes of the prompt
|
|
type: object
|
|
number:
|
|
description: Priority number in the queue
|
|
type: number
|
|
prompt_id:
|
|
description: Unique identifier for the prompt execution
|
|
format: uuid
|
|
type: string
|
|
type: object
|
|
PublishWorkflowAssetsRequest:
|
|
description: Request body for publishing workflow assets to the Hub.
|
|
properties:
|
|
asset_ids:
|
|
description: IDs of assets (inputs and models) to snapshot.
|
|
items:
|
|
type: string
|
|
type: array
|
|
required:
|
|
- asset_ids
|
|
type: object
|
|
PublishedWorkflowDetail:
|
|
description: Full detail of a publicly published workflow on the Hub.
|
|
properties:
|
|
assets:
|
|
description: Published assets with their library status for the caller.
|
|
items:
|
|
$ref: '#/components/schemas/AssetInfo'
|
|
type: array
|
|
listed:
|
|
type: boolean
|
|
name:
|
|
description: Human-readable workflow name.
|
|
type: string
|
|
publish_time:
|
|
format: date-time
|
|
nullable: true
|
|
type: string
|
|
share_id:
|
|
type: string
|
|
workflow_id:
|
|
type: string
|
|
workflow_json:
|
|
additionalProperties: true
|
|
description: The workflow JSON content at publish time.
|
|
type: object
|
|
required:
|
|
- share_id
|
|
- workflow_id
|
|
- name
|
|
- listed
|
|
- workflow_json
|
|
- assets
|
|
type: object
|
|
QueueInfo:
|
|
description: Queue information with pending and running jobs
|
|
properties:
|
|
queue_pending:
|
|
description: Array of pending job items (ordered by creation time, oldest first)
|
|
items:
|
|
description: |
|
|
Queue item tuple format: [job_number, prompt_id, workflow_json, output_node_ids, metadata]
|
|
- [0] job_number (integer): Position in queue (1-based)
|
|
- [1] prompt_id (string): Job UUID
|
|
- [2] workflow_json (object): Full ComfyUI workflow
|
|
- [3] output_node_ids (array): Node IDs to return results from
|
|
- [4] metadata (object): Contains {create_time: <milliseconds>}
|
|
items: {}
|
|
maxItems: 5
|
|
minItems: 5
|
|
type: array
|
|
type: array
|
|
queue_running:
|
|
description: Array of currently running job items
|
|
items:
|
|
description: |
|
|
Queue item tuple format: [job_number, prompt_id, workflow_json, output_node_ids, metadata]
|
|
- [0] job_number (integer): Position in queue (1-based)
|
|
- [1] prompt_id (string): Job UUID
|
|
- [2] workflow_json (object): Full ComfyUI workflow
|
|
- [3] output_node_ids (array): Node IDs to return results from
|
|
- [4] metadata (object): Contains {create_time: <milliseconds>}
|
|
items: {}
|
|
maxItems: 5
|
|
minItems: 5
|
|
type: array
|
|
type: array
|
|
type: object
|
|
QueueManageRequest:
|
|
additionalProperties: false
|
|
description: Request to manage queue operations
|
|
properties:
|
|
clear:
|
|
description: If true, clear all pending jobs from the queue
|
|
type: boolean
|
|
delete:
|
|
description: Array of PENDING job IDs to cancel
|
|
items:
|
|
type: string
|
|
type: array
|
|
type: object
|
|
QueueManageResponse:
|
|
description: Response after a queue management action (delete or clear).
|
|
properties:
|
|
cleared:
|
|
description: Whether the queue was cleared
|
|
type: boolean
|
|
deleted:
|
|
description: Array of job IDs that were successfully cancelled
|
|
items:
|
|
type: string
|
|
type: array
|
|
type: object
|
|
SystemStatsResponse:
|
|
description: System statistics response
|
|
properties:
|
|
devices:
|
|
items:
|
|
properties:
|
|
name:
|
|
description: Device name
|
|
type: string
|
|
type:
|
|
description: Device type
|
|
type: string
|
|
vram_free:
|
|
description: Free VRAM in bytes
|
|
type: number
|
|
vram_total:
|
|
description: Total VRAM in bytes
|
|
type: number
|
|
required:
|
|
- name
|
|
- type
|
|
type: object
|
|
type: array
|
|
system:
|
|
properties:
|
|
argv:
|
|
description: Command line arguments
|
|
items:
|
|
type: string
|
|
type: array
|
|
cloud_version:
|
|
description: Cloud ingest service version (commit hash)
|
|
type: string
|
|
comfyui_frontend_version:
|
|
description: ComfyUI frontend version (commit hash or tag)
|
|
type: string
|
|
comfyui_version:
|
|
description: ComfyUI version
|
|
type: string
|
|
deploy_environment:
|
|
description: How this ComfyUI instance is deployed (e.g. cloud, local-git, local-portable, local-desktop)
|
|
type: string
|
|
embedded_python:
|
|
description: Whether using embedded Python
|
|
type: boolean
|
|
os:
|
|
description: Operating system
|
|
type: string
|
|
python_version:
|
|
description: Python version
|
|
type: string
|
|
pytorch_version:
|
|
description: PyTorch version
|
|
type: string
|
|
ram_free:
|
|
description: Free RAM in bytes
|
|
type: number
|
|
ram_total:
|
|
description: Total RAM in bytes
|
|
type: number
|
|
workflow_templates_version:
|
|
description: Workflow templates version
|
|
type: string
|
|
required:
|
|
- os
|
|
- python_version
|
|
- embedded_python
|
|
- comfyui_version
|
|
- pytorch_version
|
|
- argv
|
|
- ram_total
|
|
- ram_free
|
|
type: object
|
|
required:
|
|
- system
|
|
- devices
|
|
type: object
|
|
TagInfo:
|
|
description: Metadata for a single tag that can be applied to assets.
|
|
properties:
|
|
count:
|
|
description: Number of assets using this tag
|
|
type: integer
|
|
name:
|
|
description: Tag name
|
|
type: string
|
|
required:
|
|
- name
|
|
- count
|
|
type: object
|
|
TagsModificationResponse:
|
|
description: Response after adding, updating, or removing tags on an asset.
|
|
properties:
|
|
added:
|
|
description: Tags that were successfully added (for add operation)
|
|
items:
|
|
type: string
|
|
type: array
|
|
already_present:
|
|
description: Tags that were already present (for add operation)
|
|
items:
|
|
type: string
|
|
type: array
|
|
not_present:
|
|
description: Tags that were not present (for remove operation)
|
|
items:
|
|
type: string
|
|
type: array
|
|
removed:
|
|
description: Tags that were successfully removed (for remove operation)
|
|
items:
|
|
type: string
|
|
type: array
|
|
total_tags:
|
|
description: All tags on the asset after the operation
|
|
items:
|
|
type: string
|
|
type: array
|
|
required:
|
|
- total_tags
|
|
type: object
|
|
TaskEntry:
|
|
description: Task data for list views
|
|
properties:
|
|
completed_at:
|
|
description: When task completed or failed (null if not finished)
|
|
format: date-time
|
|
type: string
|
|
create_time:
|
|
description: Task creation timestamp
|
|
format: date-time
|
|
type: string
|
|
id:
|
|
description: Unique task identifier
|
|
format: uuid
|
|
type: string
|
|
started_at:
|
|
description: When task execution started (null if not started)
|
|
format: date-time
|
|
type: string
|
|
status:
|
|
description: Current task status
|
|
enum:
|
|
- created
|
|
- running
|
|
- completed
|
|
- failed
|
|
type: string
|
|
task_name:
|
|
description: Task type name (e.g., model_upload)
|
|
type: string
|
|
required:
|
|
- id
|
|
- task_name
|
|
- status
|
|
- create_time
|
|
type: object
|
|
TaskResponse:
|
|
description: Full task details including payload and result
|
|
properties:
|
|
completed_at:
|
|
description: When task completed or failed (null if not finished)
|
|
format: date-time
|
|
type: string
|
|
create_time:
|
|
description: Task creation timestamp
|
|
format: date-time
|
|
type: string
|
|
error_message:
|
|
description: Error message on failure (null if not failed)
|
|
type: string
|
|
id:
|
|
description: Unique task identifier
|
|
format: uuid
|
|
type: string
|
|
idempotency_key:
|
|
description: Caller-provided key for idempotent task creation
|
|
type: string
|
|
payload:
|
|
additionalProperties: true
|
|
description: Task input data
|
|
type: object
|
|
result:
|
|
additionalProperties: true
|
|
description: Task output data (null if not completed)
|
|
type: object
|
|
started_at:
|
|
description: When task execution started (null if not started)
|
|
format: date-time
|
|
type: string
|
|
status:
|
|
description: Current task status
|
|
enum:
|
|
- created
|
|
- running
|
|
- completed
|
|
- failed
|
|
type: string
|
|
task_name:
|
|
description: Task type name (e.g., model_upload)
|
|
type: string
|
|
update_time:
|
|
description: Task last update timestamp
|
|
format: date-time
|
|
type: string
|
|
required:
|
|
- id
|
|
- idempotency_key
|
|
- task_name
|
|
- payload
|
|
- status
|
|
- create_time
|
|
- update_time
|
|
type: object
|
|
TasksListResponse:
|
|
description: Paginated list of background tasks for the authenticated user.
|
|
properties:
|
|
pagination:
|
|
$ref: '#/components/schemas/PaginationInfo'
|
|
tasks:
|
|
description: Array of tasks ordered by create_time
|
|
items:
|
|
$ref: '#/components/schemas/TaskEntry'
|
|
type: array
|
|
required:
|
|
- tasks
|
|
- pagination
|
|
type: object
|
|
UpdateWorkflowRequest:
|
|
description: Request body for updating an existing saved workflow.
|
|
properties:
|
|
default_view:
|
|
description: New default view mode
|
|
enum:
|
|
- workflow
|
|
- app
|
|
type: string
|
|
description:
|
|
description: New description
|
|
type: string
|
|
name:
|
|
description: New display name
|
|
type: string
|
|
type: object
|
|
UserDataResponseFull:
|
|
description: User data listing entry with file metadata (path, size, modification time).
|
|
properties:
|
|
modified:
|
|
description: UNIX timestamp of the last modification in milliseconds.
|
|
format: int64
|
|
type: integer
|
|
path:
|
|
type: string
|
|
size:
|
|
type: integer
|
|
type: object
|
|
UserResponse:
|
|
description: User information response
|
|
properties:
|
|
id:
|
|
description: Firebase UID of the authenticated user
|
|
type: string
|
|
status:
|
|
description: User status (always "active" for authenticated users)
|
|
type: string
|
|
required:
|
|
- id
|
|
- status
|
|
type: object
|
|
WorkflowForkedFrom:
|
|
description: Reference to the parent workflow from which this workflow was forked.
|
|
properties:
|
|
workflow_id:
|
|
type: string
|
|
workflow_version_id:
|
|
type: string
|
|
type: object
|
|
WorkflowListResponse:
|
|
description: Paginated list of saved workflows.
|
|
properties:
|
|
data:
|
|
items:
|
|
$ref: '#/components/schemas/WorkflowResponse'
|
|
type: array
|
|
pagination:
|
|
$ref: '#/components/schemas/PaginationInfo'
|
|
required:
|
|
- data
|
|
- pagination
|
|
type: object
|
|
WorkflowPublishInfo:
|
|
description: Publishing metadata for a workflow shared to the Hub.
|
|
properties:
|
|
assets:
|
|
description: Published assets (inputs and models).
|
|
items:
|
|
$ref: '#/components/schemas/AssetInfo'
|
|
type: array
|
|
listed:
|
|
type: boolean
|
|
publish_time:
|
|
format: date-time
|
|
nullable: true
|
|
type: string
|
|
share_id:
|
|
type: string
|
|
workflow_id:
|
|
type: string
|
|
required:
|
|
- workflow_id
|
|
- share_id
|
|
- listed
|
|
- assets
|
|
type: object
|
|
WorkflowResponse:
|
|
description: Full workflow entity including metadata and version history.
|
|
properties:
|
|
created_at:
|
|
format: date-time
|
|
type: string
|
|
created_by:
|
|
type: string
|
|
default_view:
|
|
enum:
|
|
- workflow
|
|
- app
|
|
type: string
|
|
description:
|
|
type: string
|
|
forked_from:
|
|
$ref: '#/components/schemas/WorkflowForkedFrom'
|
|
id:
|
|
type: string
|
|
latest_version:
|
|
type: integer
|
|
name:
|
|
type: string
|
|
updated_at:
|
|
format: date-time
|
|
type: string
|
|
required:
|
|
- id
|
|
- latest_version
|
|
- created_by
|
|
- created_at
|
|
- updated_at
|
|
type: object
|
|
WorkflowVersionContentResponse:
|
|
description: Full workflow version including the serialized workflow JSON.
|
|
properties:
|
|
created_at:
|
|
format: date-time
|
|
type: string
|
|
created_by:
|
|
type: string
|
|
dependency_asset_ids:
|
|
items:
|
|
type: string
|
|
type: array
|
|
id:
|
|
type: string
|
|
version:
|
|
type: integer
|
|
workflow_json:
|
|
additionalProperties: true
|
|
type: object
|
|
required:
|
|
- id
|
|
- version
|
|
- workflow_json
|
|
- created_by
|
|
- created_at
|
|
type: object
|
|
WorkflowVersionResponse:
|
|
description: Metadata for a single workflow version.
|
|
properties:
|
|
created_at:
|
|
format: date-time
|
|
type: string
|
|
created_by:
|
|
type: string
|
|
id:
|
|
type: string
|
|
latest_version:
|
|
type: integer
|
|
version:
|
|
type: integer
|
|
required:
|
|
- id
|
|
- version
|
|
- latest_version
|
|
- created_by
|
|
- created_at
|
|
type: object
|
|
securitySchemes:
|
|
ApiKeyAuth:
|
|
description: |
|
|
API key authentication. Keys are prefixed with 'comfyui-' and can be
|
|
generated from user account settings. Example: 'comfyui-abc123...'
|
|
in: header
|
|
name: X-API-Key
|
|
type: apiKey
|
|
BearerAuth:
|
|
bearerFormat: JWT
|
|
description: |
|
|
Firebase JWT token authentication. Obtain a token by authenticating
|
|
with Firebase and pass it in the Authorization header.
|
|
scheme: bearer
|
|
type: http
|
|
CookieAuth:
|
|
description: |
|
|
Session cookie authentication. Set automatically after successful
|
|
login via the /api/auth/session endpoint.
|
|
in: cookie
|
|
name: session
|
|
type: apiKey
|
|
info:
|
|
description: |
|
|
API for ComfyUI - A powerful and modular UI for Stable Diffusion.
|
|
|
|
This API allows you to interact with ComfyUI programmatically, including:
|
|
- Retrieving prompt information
|
|
- Retrieving node information
|
|
license:
|
|
name: GNU General Public License v3.0
|
|
url: https://github.com/Comfy-Org/ComfyUI/blob/master/LICENSE
|
|
title: ComfyUI API
|
|
version: 1.0.0
|
|
openapi: 3.0.3
|
|
paths:
|
|
/api/assets:
|
|
get:
|
|
description: |
|
|
Retrieves a paginated list of assets belonging to the authenticated user.
|
|
Supports filtering by tags, name, metadata, and sorting options.
|
|
operationId: listAssets
|
|
parameters:
|
|
- description: Filter assets that have ALL of these tags
|
|
explode: false
|
|
in: query
|
|
name: include_tags
|
|
schema:
|
|
items:
|
|
type: string
|
|
type: array
|
|
style: form
|
|
- description: Exclude assets that have ANY of these tags
|
|
explode: false
|
|
in: query
|
|
name: exclude_tags
|
|
schema:
|
|
items:
|
|
type: string
|
|
type: array
|
|
style: form
|
|
- description: Filter assets where name contains this substring (case-insensitive)
|
|
in: query
|
|
name: name_contains
|
|
schema:
|
|
type: string
|
|
- description: JSON object for filtering by metadata fields
|
|
in: query
|
|
name: metadata_filter
|
|
schema:
|
|
type: string
|
|
- description: Maximum number of assets to return (1-500)
|
|
in: query
|
|
name: limit
|
|
schema:
|
|
default: 20
|
|
maximum: 500
|
|
minimum: 1
|
|
type: integer
|
|
- description: Number of assets to skip for pagination
|
|
in: query
|
|
name: offset
|
|
schema:
|
|
default: 0
|
|
minimum: 0
|
|
type: integer
|
|
- description: Field to sort by
|
|
in: query
|
|
name: sort
|
|
schema:
|
|
default: created_at
|
|
enum:
|
|
- name
|
|
- created_at
|
|
- updated_at
|
|
- size
|
|
- last_access_time
|
|
type: string
|
|
- description: Sort order
|
|
in: query
|
|
name: order
|
|
schema:
|
|
default: desc
|
|
enum:
|
|
- asc
|
|
- desc
|
|
type: string
|
|
- description: Whether to include public/shared assets in results
|
|
in: query
|
|
name: include_public
|
|
schema:
|
|
default: true
|
|
type: boolean
|
|
- description: Filter assets by exact content hash.
|
|
in: query
|
|
name: hash
|
|
schema:
|
|
type: string
|
|
- description: |
|
|
Opaque cursor for keyset pagination. Pass the `next_cursor` value
|
|
from the previous response to fetch the next page. When provided,
|
|
`offset` is ignored. Cursor pagination is only supported with
|
|
`sort` values `created_at`, `updated_at`, `name`, or `size`;
|
|
requests combining `after` with other sort fields return 400.
|
|
The cursor must have been minted under the same `sort` value used
|
|
in the follow-up request.
|
|
in: query
|
|
name: after
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ListAssetsResponse'
|
|
description: Success - Assets returned
|
|
"400":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Invalid request parameters
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: List user assets
|
|
tags:
|
|
- file
|
|
post:
|
|
description: |
|
|
Creates a new asset from a direct file upload (multipart/form-data) with associated metadata.
|
|
|
|
If an asset with the same hash already exists, returns the existing asset.
|
|
operationId: createAsset
|
|
requestBody:
|
|
content:
|
|
multipart/form-data:
|
|
schema:
|
|
properties:
|
|
file:
|
|
description: The asset file to upload
|
|
format: binary
|
|
type: string
|
|
hash:
|
|
description: Content hash of the file.
|
|
pattern: ^(blake3|sha256):[a-f0-9]{64}$
|
|
type: string
|
|
id:
|
|
description: Optional asset ID for idempotent creation. If provided and asset exists, returns existing asset.
|
|
format: uuid
|
|
type: string
|
|
mime_type:
|
|
description: MIME type of the asset (e.g., "image/png", "video/mp4")
|
|
type: string
|
|
name:
|
|
description: Display name for the asset
|
|
type: string
|
|
preview_id:
|
|
description: Optional preview asset ID. If not provided, images will use their own ID as preview.
|
|
format: uuid
|
|
type: string
|
|
tags:
|
|
description: JSON-encoded array of freeform tag strings, e.g. '["models","checkpoint"]'. Common types include "models", "input", "output", and "temp", but any tag can be used in any order.
|
|
type: string
|
|
user_metadata:
|
|
description: Custom JSON metadata as a string
|
|
type: string
|
|
required:
|
|
- file
|
|
type: object
|
|
required: true
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/AssetCreated'
|
|
description: |
|
|
Asset already existed for this user (deduplicated by content hash); the
|
|
existing asset is returned with created_new=false.
|
|
"201":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/AssetCreated'
|
|
description: Asset created successfully (created_new=true)
|
|
"400":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Invalid request (bad file, invalid content type, etc.)
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"413":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: File too large
|
|
"415":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unsupported media type
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Create a new asset
|
|
tags:
|
|
- file
|
|
/api/assets/{id}:
|
|
delete:
|
|
description: Deletes the asset record.
|
|
operationId: deleteAsset
|
|
parameters:
|
|
- description: Asset ID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
schema:
|
|
format: uuid
|
|
type: string
|
|
responses:
|
|
"204":
|
|
description: Asset record deleted successfully
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Asset not found
|
|
"409":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: 'Asset cannot be deleted because it is referenced by another resource, e.g. a workflow version (error code: ASSET_IN_USE)'
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Delete asset
|
|
tags:
|
|
- file
|
|
get:
|
|
description: Retrieves detailed information about a specific asset
|
|
operationId: getAssetById
|
|
parameters:
|
|
- description: Asset ID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
schema:
|
|
format: uuid
|
|
type: string
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Asset'
|
|
description: Asset details retrieved successfully
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Asset not found
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Get asset details
|
|
tags:
|
|
- file
|
|
put:
|
|
description: |
|
|
Updates an asset's metadata. At least one field must be provided.
|
|
Only name, mime_type, preview_id, and user_metadata can be updated.
|
|
For tag management, use POST (add) and DELETE (remove) /api/assets/{id}/tags.
|
|
operationId: updateAsset
|
|
parameters:
|
|
- description: Asset ID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
schema:
|
|
format: uuid
|
|
type: string
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
minProperties: 1
|
|
properties:
|
|
mime_type:
|
|
description: Updated MIME type of the asset
|
|
type: string
|
|
name:
|
|
description: New display name for the asset
|
|
type: string
|
|
preview_id:
|
|
description: Updated preview asset ID
|
|
format: uuid
|
|
type: string
|
|
user_metadata:
|
|
additionalProperties: true
|
|
description: Updated custom metadata
|
|
type: object
|
|
type: object
|
|
required: true
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/AssetUpdated'
|
|
description: Asset updated successfully
|
|
"400":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Invalid request (no fields provided)
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Asset not found
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Update asset metadata
|
|
tags:
|
|
- file
|
|
/api/assets/{id}/tags:
|
|
delete:
|
|
description: Removes one or more tags from an existing asset
|
|
operationId: removeAssetTags
|
|
parameters:
|
|
- description: Asset ID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
schema:
|
|
format: uuid
|
|
type: string
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
properties:
|
|
tags:
|
|
description: Tags to remove from the asset
|
|
items:
|
|
type: string
|
|
minItems: 1
|
|
type: array
|
|
required:
|
|
- tags
|
|
type: object
|
|
required: true
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/TagsModificationResponse'
|
|
description: Tags removed successfully
|
|
"400":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Invalid request
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Asset not found
|
|
"422":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Validation error (e.g., reserved tag)
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Remove tags from asset
|
|
tags:
|
|
- file
|
|
post:
|
|
description: Adds one or more tags to an existing asset
|
|
operationId: addAssetTags
|
|
parameters:
|
|
- description: Asset ID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
schema:
|
|
format: uuid
|
|
type: string
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
properties:
|
|
tags:
|
|
description: Tags to add to the asset
|
|
items:
|
|
type: string
|
|
minItems: 1
|
|
type: array
|
|
required:
|
|
- tags
|
|
type: object
|
|
required: true
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/TagsModificationResponse'
|
|
description: Tags added successfully
|
|
"400":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Invalid request
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Asset not found
|
|
"422":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Validation error (e.g., reserved tag)
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Add tags to asset
|
|
tags:
|
|
- file
|
|
/api/assets/from-hash:
|
|
post:
|
|
description: |
|
|
Creates a new asset reference using an existing asset's hash.
|
|
This avoids re-uploading the file content when the asset already exists in storage.
|
|
The user can provide their own metadata and tags for the reference.
|
|
operationId: createAssetFromHash
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
properties:
|
|
hash:
|
|
description: 'Blake3 content hash of the existing asset (blake3: prefix)'
|
|
pattern: ^blake3:[a-f0-9]{64}$
|
|
type: string
|
|
mime_type:
|
|
description: MIME type of the asset (e.g., "image/png", "video/mp4")
|
|
type: string
|
|
name:
|
|
description: Display name for the asset reference (optional)
|
|
type: string
|
|
tags:
|
|
description: Freeform tags for the asset. Common types include "models", "input", "output", and "temp", but any tag can be used in any order.
|
|
items:
|
|
type: string
|
|
minItems: 1
|
|
type: array
|
|
user_metadata:
|
|
additionalProperties: true
|
|
description: Custom metadata for this asset reference
|
|
type: object
|
|
required:
|
|
- hash
|
|
- tags
|
|
type: object
|
|
required: true
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/AssetCreated'
|
|
description: |
|
|
Asset reference already existed for this user (deduplicated by content
|
|
hash); the existing asset is returned with created_new=false.
|
|
"201":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/AssetCreated'
|
|
description: Asset reference created successfully (created_new=true)
|
|
"400":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Invalid request (bad hash format, invalid tags, etc.)
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Source asset with given hash not found
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Create asset reference from existing hash
|
|
tags:
|
|
- file
|
|
/api/assets/hash/{hash}:
|
|
head:
|
|
description: |
|
|
Checks if an asset exists in the system by its blake3 hash.
|
|
Returns 200 if the asset exists, 404 if it doesn't.
|
|
operationId: checkAssetByHash
|
|
parameters:
|
|
- description: Blake3 hash of the asset in format 'blake3:hex_digest'
|
|
in: path
|
|
name: hash
|
|
required: true
|
|
schema:
|
|
example: blake3:a1b2c3d4e5f67890123456789012345678901234567890123456789012345678
|
|
pattern: ^blake3:[a-f0-9]{64}$
|
|
type: string
|
|
responses:
|
|
"200":
|
|
description: Asset exists
|
|
"400":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Invalid hash format
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"404":
|
|
description: Asset not found
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Check if asset exists by hash
|
|
tags:
|
|
- file
|
|
/api/assets/prune:
|
|
post:
|
|
description: Starts a background job that removes asset entries whose underlying content no longer exists on disk.
|
|
operationId: pruneAssets
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
properties:
|
|
marked:
|
|
description: Number of assets marked as missing
|
|
type: integer
|
|
status:
|
|
type: string
|
|
type: object
|
|
description: Prune result
|
|
summary: Mark assets whose backing files no longer exist on disk
|
|
/api/assets/seed:
|
|
post:
|
|
description: Starts a background job that scans configured directories and registers assets not yet in the asset database.
|
|
operationId: seedAssets
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
properties:
|
|
roots:
|
|
description: Root folder paths to scan (if omitted, scans all)
|
|
items:
|
|
type: string
|
|
type: array
|
|
type: object
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
properties:
|
|
status:
|
|
type: string
|
|
type: object
|
|
description: Seed started
|
|
summary: Trigger asset scan/seed from filesystem
|
|
/api/assets/seed/cancel:
|
|
post:
|
|
description: Requests cancellation of the currently-running asset seed job.
|
|
operationId: cancelAssetSeed
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
properties:
|
|
status:
|
|
type: string
|
|
type: object
|
|
description: Scan cancelled
|
|
summary: Cancel an in-progress asset scan
|
|
/api/assets/seed/status:
|
|
get:
|
|
description: Returns progress/status of the most recent asset seed job.
|
|
operationId: getAssetSeedStatus
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
additionalProperties: true
|
|
description: Scan progress details (files scanned, total, status, etc.)
|
|
type: object
|
|
description: Scan progress
|
|
summary: Get asset scan progress
|
|
/api/assets/tags/refine:
|
|
get:
|
|
description: |
|
|
Returns a histogram of tags appearing on assets matching the given filters.
|
|
Useful for refining asset searches by showing available tags and their counts.
|
|
Only returns tags with non-zero counts (tags that exist on matching assets).
|
|
operationId: getAssetTagHistogram
|
|
parameters:
|
|
- description: Filter assets that have ALL of these tags
|
|
explode: false
|
|
in: query
|
|
name: include_tags
|
|
schema:
|
|
items:
|
|
type: string
|
|
type: array
|
|
style: form
|
|
- description: Exclude assets that have ANY of these tags
|
|
explode: false
|
|
in: query
|
|
name: exclude_tags
|
|
schema:
|
|
items:
|
|
type: string
|
|
type: array
|
|
style: form
|
|
- description: Filter assets where name contains this substring (case-insensitive)
|
|
in: query
|
|
name: name_contains
|
|
schema:
|
|
type: string
|
|
- description: JSON object for filtering by metadata fields
|
|
in: query
|
|
name: metadata_filter
|
|
schema:
|
|
type: string
|
|
- description: Maximum number of tags to return (1-1000, default 100)
|
|
in: query
|
|
name: limit
|
|
schema:
|
|
default: 100
|
|
maximum: 1000
|
|
minimum: 1
|
|
type: integer
|
|
- description: Whether to include public/shared assets in results
|
|
in: query
|
|
name: include_public
|
|
schema:
|
|
default: true
|
|
type: boolean
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/AssetTagHistogramResponse'
|
|
description: Success - Tag histogram returned
|
|
"400":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Invalid request parameters
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Get tag histogram for filtered assets
|
|
tags:
|
|
- file
|
|
/api/embeddings:
|
|
get:
|
|
description: Returns the list of text-encoder embeddings available on disk.
|
|
operationId: getEmbeddings
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
items:
|
|
type: string
|
|
type: array
|
|
description: Embedding names
|
|
summary: List available embedding names
|
|
/api/experiment/models:
|
|
get:
|
|
description: |
|
|
Returns a list of model folders available in the system.
|
|
This is an experimental endpoint that replaces the legacy /models endpoint.
|
|
operationId: getModelFolders
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
items:
|
|
$ref: '#/components/schemas/ModelFolder'
|
|
type: array
|
|
description: Success - List of model folders
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
security: []
|
|
summary: Get available model folders
|
|
tags:
|
|
- file
|
|
/api/experiment/models/{folder}:
|
|
get:
|
|
description: |
|
|
Returns a list of models available in the specified folder.
|
|
This is an experimental endpoint that provides enhanced model information.
|
|
operationId: getModelsInFolder
|
|
parameters:
|
|
- description: The folder name to list models from
|
|
in: path
|
|
name: folder
|
|
required: true
|
|
schema:
|
|
example: checkpoints
|
|
type: string
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
items:
|
|
$ref: '#/components/schemas/ModelFile'
|
|
type: array
|
|
description: Success - List of models in the folder
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Folder not found or no models in folder
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
security: []
|
|
summary: Get models in a specific folder
|
|
tags:
|
|
- file
|
|
/api/extensions:
|
|
get:
|
|
description: |
|
|
Returns the list of custom node web extension JS files available for
|
|
loading by the ComfyUI frontend. Paths are relative to the web root
|
|
(e.g. `/extensions/VHS.core.js`).
|
|
operationId: getExtensions
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
description: URL paths (relative to web root) of available extension JS files
|
|
items:
|
|
type: string
|
|
type: array
|
|
description: JSON array of extension file paths
|
|
security: []
|
|
summary: List custom node JS extensions
|
|
tags:
|
|
- node
|
|
/api/features:
|
|
get:
|
|
description: Returns the server's feature capabilities
|
|
operationId: getFeatures
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
additionalProperties: true
|
|
properties:
|
|
max_upload_size:
|
|
description: Maximum upload size in bytes
|
|
type: integer
|
|
supports_preview_metadata:
|
|
description: Whether the server supports preview metadata
|
|
type: boolean
|
|
type: object
|
|
description: Success
|
|
headers:
|
|
Cache-Control:
|
|
description: Short-lived private cache to deduplicate rapid-fire calls from the frontend
|
|
schema:
|
|
type: string
|
|
Vary:
|
|
description: Cache key includes auth headers so anonymous and authenticated responses are stored separately
|
|
schema:
|
|
type: string
|
|
security:
|
|
- ApiKeyAuth: []
|
|
- BearerAuth: []
|
|
- CookieAuth: []
|
|
- {}
|
|
summary: Get server feature flags
|
|
tags:
|
|
- node
|
|
/api/feedback:
|
|
post:
|
|
description: Submit feedback about the ComfyUI service
|
|
operationId: submitFeedback
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/FeedbackRequest'
|
|
required: true
|
|
responses:
|
|
"201":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/FeedbackResponse'
|
|
description: Feedback submitted successfully
|
|
"400":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Invalid request
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Submit user feedback
|
|
tags:
|
|
- feedback
|
|
/api/files/mask-layers:
|
|
get:
|
|
description: |
|
|
Given a mask file (any of the 4 layers), returns all related mask layer files.
|
|
This is used by the mask editor to load the paint, mask, and painted layers
|
|
when reopening a previously edited mask.
|
|
operationId: getMaskLayers
|
|
parameters:
|
|
- description: Hash filename of any mask layer file
|
|
in: query
|
|
name: filename
|
|
required: true
|
|
schema:
|
|
example: abc123def456.png
|
|
type: string
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
properties:
|
|
mask:
|
|
description: Filename of the mask layer
|
|
nullable: true
|
|
type: string
|
|
paint:
|
|
description: Filename of the paint strokes layer
|
|
nullable: true
|
|
type: string
|
|
painted:
|
|
description: Filename of the painted image layer
|
|
nullable: true
|
|
type: string
|
|
painted_masked:
|
|
description: Filename of the final composite layer
|
|
nullable: true
|
|
type: string
|
|
type: object
|
|
description: Success - Related mask layers returned
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: File not found or not a mask file
|
|
summary: Get related mask layer files
|
|
tags:
|
|
- file
|
|
/api/free:
|
|
post:
|
|
description: Frees GPU memory by unloading models and/or freeing the resident model cache.
|
|
operationId: freeMemory
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
properties:
|
|
free_memory:
|
|
description: Run garbage collection and free cached memory
|
|
type: boolean
|
|
unload_models:
|
|
description: Unload all models from VRAM/RAM
|
|
type: boolean
|
|
type: object
|
|
responses:
|
|
"200":
|
|
description: Memory freed
|
|
summary: Free GPU memory and/or unload models
|
|
/api/global_subgraphs:
|
|
get:
|
|
description: |
|
|
Returns a list of globally available subgraph blueprints.
|
|
These are pre-built workflow components that can be used as nodes.
|
|
The data field contains a promise that resolves to the full subgraph JSON.
|
|
operationId: getGlobalSubgraphs
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
additionalProperties:
|
|
$ref: '#/components/schemas/GlobalSubgraphInfo'
|
|
type: object
|
|
description: Success - Map of subgraph IDs to their metadata
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
security: []
|
|
summary: Get available subgraph blueprints
|
|
tags:
|
|
- workflow
|
|
/api/global_subgraphs/{id}:
|
|
get:
|
|
description: Returns the full data for a specific subgraph blueprint by ID
|
|
operationId: getGlobalSubgraph
|
|
parameters:
|
|
- description: The unique identifier of the subgraph blueprint
|
|
in: path
|
|
name: id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/GlobalSubgraphData'
|
|
description: Success - Full subgraph data
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Subgraph not found
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
security: []
|
|
summary: Get a specific subgraph blueprint
|
|
tags:
|
|
- workflow
|
|
/api/history:
|
|
post:
|
|
deprecated: true
|
|
description: |
|
|
**Deprecated.** Superseded by the job-management endpoints under
|
|
`/api/jobs`. Planned for removal no earlier than a future major
|
|
release; sunset timeline TBD.
|
|
|
|
Clear all history for the authenticated user or delete specific job IDs.
|
|
Supports clearing all history or deleting specific job IDs.
|
|
operationId: manageHistory
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/HistoryManageRequest'
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: Success - History management operation completed
|
|
"400":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Invalid request parameters
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized - Authentication required
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Manage execution history
|
|
tags:
|
|
- workflow
|
|
/api/history_v2:
|
|
get:
|
|
deprecated: true
|
|
description: |
|
|
**Deprecated.** Superseded by `GET /api/jobs`, which returns the same
|
|
execution records in a paginated, filterable format. Planned for removal
|
|
no earlier than a future major release; sunset timeline TBD.
|
|
|
|
Retrieve execution history for the authenticated user with pagination support.
|
|
Returns a lightweight history format with filtered prompt data (workflow removed from extra_pnginfo).
|
|
operationId: getHistory
|
|
parameters:
|
|
- description: Maximum number of items to return
|
|
in: query
|
|
name: max_items
|
|
schema:
|
|
type: integer
|
|
- description: Starting position (default 0)
|
|
in: query
|
|
name: offset
|
|
schema:
|
|
default: 0
|
|
type: integer
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/HistoryResponse'
|
|
description: Success - Execution history retrieved
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized - Authentication required
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Get execution history (v2)
|
|
tags:
|
|
- workflow
|
|
/api/history_v2/{prompt_id}:
|
|
get:
|
|
deprecated: true
|
|
description: |
|
|
**Deprecated.** Superseded by `GET /api/jobs/{job_id}`, which returns
|
|
the same execution record. Planned for removal no earlier than a future
|
|
major release; sunset timeline TBD.
|
|
|
|
Retrieve detailed execution history for a specific prompt ID.
|
|
Returns full history data including complete prompt information.
|
|
operationId: getHistoryForPrompt
|
|
parameters:
|
|
- description: The prompt ID to retrieve history for
|
|
in: path
|
|
name: prompt_id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/HistoryDetailResponse'
|
|
description: Success - History for prompt retrieved
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized - Authentication required
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Prompt not found
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Get history for specific prompt
|
|
tags:
|
|
- workflow
|
|
/api/i18n:
|
|
get:
|
|
description: Returns translation file URLs contributed by custom nodes, keyed by locale.
|
|
operationId: getI18n
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
additionalProperties: true
|
|
description: Nested map of locale to translation key-value pairs
|
|
type: object
|
|
description: Translation map
|
|
summary: Get internationalisation translation strings
|
|
/api/interrupt:
|
|
post:
|
|
description: |
|
|
Cancel all currently RUNNING jobs for the authenticated user.
|
|
This will interrupt any job that is currently in 'in_progress' status.
|
|
Note: This endpoint only affects running jobs. To cancel pending jobs, use /api/queue.
|
|
operationId: interruptJob
|
|
responses:
|
|
"200":
|
|
description: Success - Job interrupted or no running job found
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized - Authentication required
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Interrupt currently running jobs
|
|
tags:
|
|
- queue
|
|
/api/job/{job_id}/status:
|
|
get:
|
|
deprecated: true
|
|
description: |
|
|
**Deprecated.** Superseded by `GET /api/jobs/{job_id}` (plural path).
|
|
Clients should migrate; the endpoint is retained for backward
|
|
compatibility but will be removed in a future release.
|
|
operationId: getJobStatus
|
|
parameters:
|
|
- description: The unique ID of the job
|
|
in: path
|
|
name: job_id
|
|
required: true
|
|
schema:
|
|
format: uuid
|
|
type: string
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/JobStatusResponse'
|
|
description: Success - Job status returned
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"403":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Forbidden - job belongs to another user
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Job not found
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Get job status (deprecated)
|
|
tags:
|
|
- job
|
|
/api/jobs:
|
|
get:
|
|
description: |
|
|
Retrieve a paginated list of jobs for the authenticated user.
|
|
Returns lightweight job data optimized for list views.
|
|
Workflow and full outputs are excluded to reduce payload size.
|
|
operationId: listJobs
|
|
parameters:
|
|
- description: Filter by one or more statuses (comma-separated). If not provided, returns all jobs.
|
|
example: pending,in_progress
|
|
in: query
|
|
name: status
|
|
schema:
|
|
type: string
|
|
- description: Filter by workflow ID (exact match)
|
|
example: 550e8400-e29b-41d4-a716-446655440000
|
|
in: query
|
|
name: workflow_id
|
|
schema:
|
|
type: string
|
|
- description: Filter by output media type (only applies to completed jobs with outputs)
|
|
example: image
|
|
in: query
|
|
name: output_type
|
|
schema:
|
|
enum:
|
|
- image
|
|
- video
|
|
- audio
|
|
- 3d
|
|
type: string
|
|
- description: Field to sort by (create_time = when job was submitted, execution_time = how long workflow took to run)
|
|
example: execution_time
|
|
in: query
|
|
name: sort_by
|
|
schema:
|
|
default: create_time
|
|
enum:
|
|
- create_time
|
|
- execution_time
|
|
type: string
|
|
- description: Sort direction (asc = ascending, desc = descending)
|
|
in: query
|
|
name: sort_order
|
|
schema:
|
|
default: desc
|
|
enum:
|
|
- asc
|
|
- desc
|
|
type: string
|
|
- description: |
|
|
Opaque cursor for keyset pagination. Pass the `next_cursor` value
|
|
from a previous response to fetch the next page.
|
|
Cursor pagination is supported only when `sort_by=create_time`
|
|
(default). If `sort_by=execution_time`, `after` is ignored and
|
|
offset/limit pagination is used.
|
|
Cursors are opaque base64url payloads — clients should treat them
|
|
as strings and not parse the contents.
|
|
example: eyJzIjoiY3JlYXRlX3RpbWUiLCJ2IjoiMTcxNjIwMDAwMDAwMDAwMCIsImlkIjoiYTFiMmMzZDQtZTVmNi03YTg5LWIwYzEtZDJlM2Y0YTViNmM3In0
|
|
in: query
|
|
name: after
|
|
schema:
|
|
type: string
|
|
- deprecated: true
|
|
description: 'Pagination offset (0-based). Deprecated: prefer cursor-based pagination via `after`.'
|
|
in: query
|
|
name: offset
|
|
schema:
|
|
default: 0
|
|
minimum: 0
|
|
type: integer
|
|
- description: Maximum items per page (1-1000)
|
|
in: query
|
|
name: limit
|
|
schema:
|
|
default: 100
|
|
maximum: 1000
|
|
minimum: 1
|
|
type: integer
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/JobsListResponse'
|
|
description: Success - Jobs retrieved
|
|
"400":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Bad request (e.g. malformed pagination cursor).
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized - Authentication required
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: List jobs with pagination and filtering
|
|
tags:
|
|
- workflow
|
|
/api/jobs/{job_id}:
|
|
get:
|
|
description: |
|
|
Retrieve complete details for a specific job including workflow and outputs.
|
|
Used for detail views, workflow re-execution, and debugging.
|
|
operationId: getJobDetail
|
|
parameters:
|
|
- description: Job identifier (UUID)
|
|
in: path
|
|
name: job_id
|
|
required: true
|
|
schema:
|
|
format: uuid
|
|
type: string
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/JobDetailResponse'
|
|
description: Success - Job details retrieved
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized - Authentication required
|
|
"403":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Forbidden - Job does not belong to user
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Job not found
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Get full job details
|
|
tags:
|
|
- workflow
|
|
/api/jobs/{job_id}/cancel:
|
|
post:
|
|
description: |
|
|
Cancel a specific job for the authenticated user.
|
|
|
|
Idempotent: a job that is already in a terminal state (completed, failed,
|
|
cancelled) or already cancelling is treated as a successful no-op and
|
|
returns 200. Only truly missing or cross-user jobs return 404.
|
|
operationId: cancelJob
|
|
parameters:
|
|
- description: Job identifier (UUID)
|
|
in: path
|
|
name: job_id
|
|
required: true
|
|
schema:
|
|
format: uuid
|
|
type: string
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/JobCancelResponse'
|
|
description: Success - Cancel request accepted (or job was already terminal)
|
|
"400":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Bad Request - job_id is not a valid UUID (emitted by request validation before the handler runs)
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized - Authentication required
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Job not found for this user
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error - cancellation failed
|
|
summary: Cancel a job
|
|
tags:
|
|
- workflow
|
|
/api/node_replacements:
|
|
get:
|
|
description: |
|
|
Returns mappings of unsupported node class names to their cloud-installed replacements.
|
|
Used by the frontend to offer "Quick Fix" when a workflow contains missing nodes.
|
|
operationId: getNodeReplacements
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
additionalProperties: true
|
|
type: object
|
|
description: Success - Node replacement mappings
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
security: []
|
|
summary: Get node replacement mappings
|
|
tags:
|
|
- node
|
|
/api/object_info:
|
|
get:
|
|
description: Returns information about all available nodes
|
|
operationId: getNodeInfo
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
additionalProperties:
|
|
$ref: '#/components/schemas/NodeInfo'
|
|
type: object
|
|
description: Success
|
|
summary: Get all node information
|
|
tags:
|
|
- node
|
|
/api/prompt:
|
|
get:
|
|
description: Returns information about the current prompt in the execution queue
|
|
operationId: getPromptInfo
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PromptInfo'
|
|
description: Success
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Get information about current prompt execution
|
|
tags:
|
|
- workflow
|
|
post:
|
|
description: |
|
|
Submit a workflow to be executed by the backend.
|
|
The workflow is a JSON object describing the nodes and their connections.
|
|
operationId: executePrompt
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PromptRequest'
|
|
required: true
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PromptResponse'
|
|
description: Success - Prompt accepted
|
|
"400":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PromptErrorResponse'
|
|
description: Invalid prompt
|
|
"402":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PromptErrorResponse'
|
|
description: Payment required - Insufficient credits
|
|
"429":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PromptErrorResponse'
|
|
description: Payment required - User has not paid
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PromptErrorResponse'
|
|
description: Internal server error
|
|
"503":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PromptErrorResponse'
|
|
description: Service unavailable
|
|
summary: Submit a workflow for execution
|
|
tags:
|
|
- workflow
|
|
/api/queue:
|
|
get:
|
|
description: Returns information about running and pending items in the queue
|
|
operationId: getQueueInfo
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/QueueInfo'
|
|
description: Success
|
|
"400":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Invalid request parameters
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Invalid request parameters
|
|
summary: Get queue information
|
|
tags:
|
|
- queue
|
|
post:
|
|
description: |
|
|
Cancel specific PENDING jobs by ID or clear all pending jobs in the queue.
|
|
Note: This endpoint only affects pending jobs. To cancel running jobs, use /api/interrupt.
|
|
operationId: manageQueue
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/QueueManageRequest'
|
|
required: true
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/QueueManageResponse'
|
|
description: Success
|
|
"400":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Invalid request parameters
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Manage queue operations
|
|
tags:
|
|
- queue
|
|
/api/settings:
|
|
get:
|
|
description: Returns all settings for the authenticated user
|
|
operationId: getAllSettings
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
additionalProperties: true
|
|
description: User settings as key-value pairs
|
|
type: object
|
|
description: Success
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
summary: Get all user settings
|
|
tags:
|
|
- settings
|
|
post:
|
|
description: Update multiple settings (merge with existing)
|
|
operationId: updateMultipleSettings
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
additionalProperties: true
|
|
description: Settings to update as key-value pairs
|
|
type: object
|
|
text/plain:
|
|
schema:
|
|
description: JSON string of settings to update
|
|
type: string
|
|
required: true
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
additionalProperties: true
|
|
description: Updated user settings
|
|
type: object
|
|
description: Success
|
|
"400":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Invalid request
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
summary: Update multiple settings
|
|
tags:
|
|
- settings
|
|
/api/settings/{id}:
|
|
get:
|
|
description: Returns a specific setting value by its id
|
|
operationId: getSettingById
|
|
parameters:
|
|
- description: Setting id to retrieve
|
|
in: path
|
|
name: id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
description: Setting value response
|
|
properties:
|
|
value:
|
|
description: The setting value
|
|
type: object
|
|
description: Success
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Setting not found
|
|
summary: Get a specific setting by id
|
|
tags:
|
|
- settings
|
|
post:
|
|
description: Update a specific setting by its id
|
|
operationId: updateSettingById
|
|
parameters:
|
|
- description: Setting id to update
|
|
in: path
|
|
name: id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
description: New value for the setting
|
|
text/plain:
|
|
schema:
|
|
description: JSON string of the new setting value
|
|
type: string
|
|
required: true
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
description: Updated setting value response
|
|
properties:
|
|
value:
|
|
description: The updated setting value
|
|
type: object
|
|
description: Success
|
|
"400":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Invalid request
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
summary: Update a specific setting by id
|
|
tags:
|
|
- settings
|
|
/api/system_stats:
|
|
get:
|
|
description: Returns system statistics including ComfyUI version, device info, and system resources
|
|
operationId: getSystemStats
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/SystemStatsResponse'
|
|
description: Success
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
security: []
|
|
summary: Get system statistics
|
|
tags:
|
|
- system
|
|
/api/tags:
|
|
get:
|
|
description: |
|
|
Retrieves a list of all tags used across assets.
|
|
Includes usage counts and filtering options.
|
|
operationId: listTags
|
|
parameters:
|
|
- description: Filter tags by prefix
|
|
in: query
|
|
name: prefix
|
|
schema:
|
|
type: string
|
|
- description: Maximum number of tags to return (1-1000)
|
|
in: query
|
|
name: limit
|
|
schema:
|
|
default: 100
|
|
maximum: 1000
|
|
minimum: 1
|
|
type: integer
|
|
- description: Number of tags to skip for pagination
|
|
in: query
|
|
name: offset
|
|
schema:
|
|
default: 0
|
|
minimum: 0
|
|
type: integer
|
|
- description: Sort order for tags
|
|
in: query
|
|
name: order
|
|
schema:
|
|
default: count_desc
|
|
enum:
|
|
- count_desc
|
|
- name_asc
|
|
type: string
|
|
- description: Include tags with zero usage count
|
|
in: query
|
|
name: include_zero
|
|
schema:
|
|
default: false
|
|
type: boolean
|
|
- description: Whether to include public/shared assets when counting tags
|
|
in: query
|
|
name: include_public
|
|
schema:
|
|
default: true
|
|
type: boolean
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ListTagsResponse'
|
|
description: Tags retrieved successfully
|
|
"400":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Invalid request parameters
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: List all tags
|
|
tags:
|
|
- file
|
|
/api/tasks:
|
|
get:
|
|
description: |
|
|
Retrieve a paginated list of background tasks for the authenticated user.
|
|
Supports filtering by task type, status, and creation time.
|
|
operationId: listTasks
|
|
parameters:
|
|
- description: Filter by task type name (exact match)
|
|
example: model_upload
|
|
in: query
|
|
name: task_name
|
|
schema:
|
|
type: string
|
|
- description: Filter by idempotency key (exact match). For best performance, specify task_name as well.
|
|
example: upload-model-abc123
|
|
in: query
|
|
name: idempotency_key
|
|
schema:
|
|
type: string
|
|
- description: Filter by one or more statuses (comma-separated)
|
|
example: created,running
|
|
in: query
|
|
name: status
|
|
schema:
|
|
type: string
|
|
- description: Filter tasks created after this timestamp (RFC3339 format)
|
|
example: "2024-01-01T00:00:00Z"
|
|
in: query
|
|
name: created_after
|
|
schema:
|
|
format: date-time
|
|
type: string
|
|
- description: Filter tasks created before this timestamp (RFC3339 format)
|
|
example: "2024-12-31T23:59:59Z"
|
|
in: query
|
|
name: created_before
|
|
schema:
|
|
format: date-time
|
|
type: string
|
|
- description: Sort direction (asc = ascending, desc = descending by create_time)
|
|
in: query
|
|
name: sort_order
|
|
schema:
|
|
default: desc
|
|
enum:
|
|
- asc
|
|
- desc
|
|
type: string
|
|
- description: Pagination offset (0-based)
|
|
in: query
|
|
name: offset
|
|
schema:
|
|
default: 0
|
|
minimum: 0
|
|
type: integer
|
|
- description: Maximum items per page (1-100)
|
|
in: query
|
|
name: limit
|
|
schema:
|
|
default: 20
|
|
maximum: 100
|
|
minimum: 1
|
|
type: integer
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/TasksListResponse'
|
|
description: Success - Tasks retrieved
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized - Authentication required
|
|
"422":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Validation error - Invalid filter values
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: List background tasks
|
|
tags:
|
|
- task
|
|
/api/tasks/{task_id}:
|
|
get:
|
|
description: |
|
|
Retrieve full details for a specific background task.
|
|
operationId: getTask
|
|
parameters:
|
|
- description: Task identifier (UUID)
|
|
in: path
|
|
name: task_id
|
|
required: true
|
|
schema:
|
|
format: uuid
|
|
type: string
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/TaskResponse'
|
|
description: Success - Task details retrieved
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized - Authentication required
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Task not found (also returned for ownership failures to avoid leaking task existence)
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Get task details
|
|
tags:
|
|
- task
|
|
/api/upload/image:
|
|
post:
|
|
description: |
|
|
Upload an image file to cloud storage.
|
|
|
|
Image limits:
|
|
- Maximum file size: 50 MB
|
|
- Maximum width/height per edge: 16384 px
|
|
- Maximum total pixel count: 64 megapixels (67108864 pixels)
|
|
|
|
Uploads that exceed any of these limits are rejected with HTTP 400.
|
|
operationId: uploadImage
|
|
requestBody:
|
|
content:
|
|
multipart/form-data:
|
|
schema:
|
|
properties:
|
|
image:
|
|
description: The image file to upload
|
|
format: binary
|
|
type: string
|
|
overwrite:
|
|
description: Whether to overwrite existing file (true/false)
|
|
type: string
|
|
subfolder:
|
|
description: Optional subfolder path
|
|
type: string
|
|
type:
|
|
description: Upload type (defaults to "output")
|
|
type: string
|
|
required:
|
|
- image
|
|
type: object
|
|
required: true
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
properties:
|
|
name:
|
|
description: Filename of the uploaded image
|
|
type: string
|
|
subfolder:
|
|
description: Subfolder path where image was saved
|
|
type: string
|
|
type:
|
|
description: Type of upload (e.g., "output")
|
|
type: string
|
|
type: object
|
|
description: Image uploaded successfully
|
|
"400":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Bad request
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Upload an image file
|
|
tags:
|
|
- file
|
|
/api/upload/mask:
|
|
post:
|
|
description: |
|
|
Upload a mask image to be applied to an existing image.
|
|
|
|
Image limits apply to both the uploaded mask and the referenced
|
|
original image:
|
|
- Maximum file size: 50 MB
|
|
- Maximum width/height per edge: 16384 px
|
|
- Maximum total pixel count: 64 megapixels (67108864 pixels)
|
|
|
|
Uploads that exceed any of these limits are rejected with HTTP 400.
|
|
operationId: uploadMask
|
|
requestBody:
|
|
content:
|
|
multipart/form-data:
|
|
schema:
|
|
properties:
|
|
image:
|
|
description: The mask image file to upload
|
|
format: binary
|
|
type: string
|
|
original_ref:
|
|
description: JSON string containing reference to the original image
|
|
type: string
|
|
required:
|
|
- image
|
|
- original_ref
|
|
type: object
|
|
required: true
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
properties:
|
|
name:
|
|
description: Filename of the uploaded mask
|
|
type: string
|
|
subfolder:
|
|
description: Subfolder path where mask was saved
|
|
type: string
|
|
type:
|
|
description: Type of upload (e.g., "output")
|
|
type: string
|
|
type: object
|
|
description: Mask uploaded successfully
|
|
"400":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Bad request
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Upload a mask image
|
|
tags:
|
|
- file
|
|
/api/user:
|
|
get:
|
|
description: Returns information about the currently authenticated user
|
|
operationId: getUser
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/UserResponse'
|
|
description: Success
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
summary: Get current user information
|
|
tags:
|
|
- user
|
|
/api/userdata:
|
|
get:
|
|
description: Returns a list of user data files in the specified directory, optionally recursively and with full metadata.
|
|
operationId: getUserdata
|
|
parameters:
|
|
- description: The directory to list files from.
|
|
in: query
|
|
name: dir
|
|
schema:
|
|
type: string
|
|
- description: Whether to list files recursively.
|
|
in: query
|
|
name: recurse
|
|
schema:
|
|
default: false
|
|
type: boolean
|
|
- description: Whether to split file information by type.
|
|
in: query
|
|
name: split
|
|
schema:
|
|
default: false
|
|
type: boolean
|
|
- description: Whether to return full file metadata.
|
|
in: query
|
|
name: full_info
|
|
schema:
|
|
default: false
|
|
type: boolean
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/GetUserDataResponseFull'
|
|
description: A list of user data files.
|
|
"400":
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: Bad request (e.g., invalid filename).
|
|
"401":
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: Unauthorized.
|
|
"404":
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: File not found or invalid path.
|
|
"500":
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: General error
|
|
summary: List user data files
|
|
tags:
|
|
- user
|
|
/api/userdata/{file}:
|
|
delete:
|
|
description: |
|
|
Delete a user data file from the database. The file parameter should be
|
|
the relative path within the user's data directory.
|
|
operationId: deleteUserdataFile
|
|
parameters:
|
|
- description: The file path to delete (URL encoded if necessary).
|
|
in: path
|
|
name: file
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"204":
|
|
description: File deleted successfully (No Content).
|
|
"401":
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: Unauthorized.
|
|
"404":
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: File not found.
|
|
"500":
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: Internal server error.
|
|
summary: Delete a user data file
|
|
tags:
|
|
- user
|
|
get:
|
|
description: Returns the requested user data file if it exists.
|
|
operationId: getUserdataFile
|
|
parameters:
|
|
- description: The filename of the user data to retrieve.
|
|
in: path
|
|
name: file
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/octet-stream:
|
|
schema:
|
|
format: binary
|
|
type: string
|
|
description: Successfully retrieved the file.
|
|
"400":
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: Bad request (e.g., invalid filename).
|
|
"401":
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: Unauthorized.
|
|
"404":
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: File not found or invalid path.
|
|
"500":
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: General error
|
|
summary: Get user data file
|
|
tags:
|
|
- user
|
|
post:
|
|
description: |
|
|
Upload a file to a user's data directory. Optional query parameters allow
|
|
control over overwrite behavior and response detail.
|
|
operationId: postUserdataFile
|
|
parameters:
|
|
- description: The target file path (URL encoded if necessary).
|
|
in: path
|
|
name: file
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- description: If "false", prevents overwriting existing files. Defaults to "true".
|
|
in: query
|
|
name: overwrite
|
|
schema:
|
|
default: "true"
|
|
enum:
|
|
- "true"
|
|
- "false"
|
|
type: string
|
|
- description: If "true", returns detailed file info; if "false", returns only the relative path.
|
|
in: query
|
|
name: full_info
|
|
schema:
|
|
default: "false"
|
|
enum:
|
|
- "true"
|
|
- "false"
|
|
type: string
|
|
requestBody:
|
|
content:
|
|
application/octet-stream:
|
|
schema:
|
|
format: binary
|
|
type: string
|
|
required: true
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/UserDataResponseFull'
|
|
description: File uploaded successfully.
|
|
"400":
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: Missing or invalid 'file' parameter.
|
|
"401":
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: Unauthorized.
|
|
"403":
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: The requested path is not allowed.
|
|
"409":
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: File already exists and overwrite is set to false.
|
|
"500":
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: General error
|
|
summary: Upload or update a user data file
|
|
tags:
|
|
- user
|
|
/api/userdata/{file}/move/{dest}:
|
|
post:
|
|
description: |
|
|
Move or rename a file within a user's data directory, with options for
|
|
controlling overwrite behavior and response format.
|
|
operationId: moveUserdataFile
|
|
parameters:
|
|
- description: The source file path (URL encoded if necessary).
|
|
in: path
|
|
name: file
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- description: The destination file path (URL encoded if necessary).
|
|
in: path
|
|
name: dest
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- description: If "false", prevents overwriting existing files. Defaults to "true".
|
|
in: query
|
|
name: overwrite
|
|
schema:
|
|
default: "true"
|
|
enum:
|
|
- "true"
|
|
- "false"
|
|
type: string
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/UserDataResponseFull'
|
|
description: File moved successfully.
|
|
"400":
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: Missing or invalid parameters.
|
|
"401":
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: Unauthorized.
|
|
"404":
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: Source file not found.
|
|
"409":
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: Destination file already exists and overwrite is set to false.
|
|
"500":
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: General error
|
|
summary: Move or rename a user data file
|
|
tags:
|
|
- user
|
|
/api/userdata/{file}/publish:
|
|
get:
|
|
description: Returns the publish status and share info for a workflow identified by its userdata path.
|
|
operationId: getUserdataFilePublish
|
|
parameters:
|
|
- description: The workflow file path within the user's data directory (URL encoded if necessary).
|
|
in: path
|
|
name: file
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/WorkflowPublishInfo'
|
|
description: Publish info (publish_time is null if never published)
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Workflow not found
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Get publish info for a workflow file
|
|
tags:
|
|
- workflows
|
|
post:
|
|
description: Creates a new published_workflow record from the latest version and snapshots the provided assets.
|
|
operationId: postUserdataFilePublish
|
|
parameters:
|
|
- description: The workflow file path within the user's data directory (URL encoded if necessary).
|
|
in: path
|
|
name: file
|
|
required: true
|
|
schema:
|
|
type: string
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PublishWorkflowAssetsRequest'
|
|
required: true
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/WorkflowPublishInfo'
|
|
description: Workflow published
|
|
"400":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Bad request
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Workflow not found
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Publish a workflow file
|
|
tags:
|
|
- workflows
|
|
/api/users:
|
|
get:
|
|
description: |
|
|
ComfyUI legacy users endpoint. Returns information about how user
|
|
data is stored. In cloud this is always server-managed, so callers
|
|
receive a constant response indicating server-side storage.
|
|
operationId: getUsersInfo
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
properties:
|
|
migrated:
|
|
description: Whether user data has been migrated (always true in cloud)
|
|
type: boolean
|
|
storage:
|
|
description: Where user data is stored (always "server" in cloud)
|
|
type: string
|
|
required:
|
|
- storage
|
|
- migrated
|
|
type: object
|
|
description: Userdata storage information
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
summary: ComfyUI userdata storage info
|
|
tags:
|
|
- user
|
|
/api/vhs/queryvideo:
|
|
get:
|
|
description: |
|
|
VHS custom node endpoint that returns metadata about a video file
|
|
(frame count, fps, resolution, duration). Currently returns default
|
|
placeholder values; real ffprobe integration is a follow-up.
|
|
operationId: getVhsQueryVideo
|
|
parameters:
|
|
- description: Name of the video file to query
|
|
in: query
|
|
name: filename
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
properties:
|
|
source:
|
|
description: Source video metadata
|
|
properties:
|
|
duration:
|
|
description: Duration in seconds
|
|
type: number
|
|
fps:
|
|
description: Frames per second
|
|
type: number
|
|
frames:
|
|
description: Total frame count
|
|
type: integer
|
|
size:
|
|
description: '[width, height] in pixels'
|
|
items:
|
|
type: integer
|
|
maxItems: 2
|
|
minItems: 2
|
|
type: array
|
|
required:
|
|
- size
|
|
- fps
|
|
- frames
|
|
- duration
|
|
type: object
|
|
required:
|
|
- source
|
|
type: object
|
|
description: Video metadata
|
|
"400":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: |
|
|
Missing required query parameter. Produced by the oapi-codegen
|
|
wrapper via echo.NewHTTPError; the custom Echo HTTPErrorHandler
|
|
normalizes it to the standard ErrorResponse {code, message} shape
|
|
(BE-1178).
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
security:
|
|
- ApiKeyAuth: []
|
|
- BearerAuth: []
|
|
- CookieAuth: []
|
|
summary: Query VHS video metadata
|
|
tags:
|
|
- file
|
|
/api/view:
|
|
get:
|
|
description: |
|
|
Retrieve and view a file from the ComfyUI file system.
|
|
This endpoint is typically used to view generated images or other output files.
|
|
Cookie auth is allowed on this endpoint because it's used by img/video tags in browsers.
|
|
operationId: viewFile
|
|
parameters:
|
|
- description: Name of the file to view
|
|
in: query
|
|
name: filename
|
|
required: true
|
|
schema:
|
|
example: ComfyUI_00004_.png
|
|
type: string
|
|
- description: Subfolder path where the file is located
|
|
in: query
|
|
name: subfolder
|
|
schema:
|
|
example: tests/foo/bar
|
|
type: string
|
|
- description: Type of file (e.g., output, input, temp)
|
|
in: query
|
|
name: type
|
|
schema:
|
|
example: output
|
|
type: string
|
|
- description: Full path to the file (used for temp files)
|
|
in: query
|
|
name: fullpath
|
|
schema:
|
|
type: string
|
|
- description: Format of the file
|
|
in: query
|
|
name: format
|
|
schema:
|
|
type: string
|
|
- description: Frame rate for video files
|
|
in: query
|
|
name: frame_rate
|
|
schema:
|
|
type: integer
|
|
- description: Workflow identifier
|
|
in: query
|
|
name: workflow
|
|
schema:
|
|
type: string
|
|
- description: Timestamp parameter
|
|
in: query
|
|
name: timestamp
|
|
schema:
|
|
example: 1234567890
|
|
type: integer
|
|
- description: |
|
|
Image channel to extract from PNG images.
|
|
- 'rgb': Return only RGB channels (alpha set to fully opaque)
|
|
- 'a' or 'alpha': Return alpha channel as grayscale image
|
|
- If not specified, return original image unchanged via redirect
|
|
in: query
|
|
name: channel
|
|
schema:
|
|
example: rgb
|
|
type: string
|
|
- description: |
|
|
Maximum dimension (width or height) to resize the image to, preserving aspect ratio.
|
|
The image is fit within a res x res box. Returns a JPEG thumbnail.
|
|
Only applies to raster image files (PNG, JPEG, WebP, GIF).
|
|
in: query
|
|
name: res
|
|
schema:
|
|
example: 256
|
|
maximum: 1024
|
|
minimum: 64
|
|
type: integer
|
|
responses:
|
|
"200":
|
|
content:
|
|
image/jpeg:
|
|
schema:
|
|
description: Resized JPEG thumbnail (returned when res parameter is used)
|
|
format: binary
|
|
type: string
|
|
image/png:
|
|
schema:
|
|
description: Processed PNG image with extracted channel
|
|
format: binary
|
|
type: string
|
|
description: Success - File content returned (used when channel or res parameter is present)
|
|
"302":
|
|
description: Redirect to GCS signed URL
|
|
headers:
|
|
Cache-Control:
|
|
description: Cache directive for the redirect response
|
|
schema:
|
|
type: string
|
|
Location:
|
|
description: Signed URL to access the file in GCS
|
|
schema:
|
|
type: string
|
|
Vary:
|
|
description: Headers that affect response caching
|
|
schema:
|
|
type: string
|
|
"400":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Invalid request parameters
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: File not found or unauthorized
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
security:
|
|
- ApiKeyAuth: []
|
|
- BearerAuth: []
|
|
- CookieAuth: []
|
|
summary: View a file
|
|
tags:
|
|
- file
|
|
/api/workflow_templates:
|
|
get:
|
|
description: Returns available workflow templates
|
|
operationId: getWorkflowTemplates
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
description: Empty object for workflow templates
|
|
type: object
|
|
description: Success
|
|
security: []
|
|
summary: Get available workflow templates
|
|
tags:
|
|
- workflow
|
|
/api/workflows:
|
|
get:
|
|
description: Returns a paginated list of workflows for the authenticated user in the current workspace.
|
|
operationId: listWorkflows
|
|
parameters:
|
|
- in: query
|
|
name: limit
|
|
schema:
|
|
default: 20
|
|
maximum: 100
|
|
type: integer
|
|
- in: query
|
|
name: offset
|
|
schema:
|
|
default: 0
|
|
type: integer
|
|
- description: Search workflows by name (case-insensitive substring match)
|
|
in: query
|
|
name: name
|
|
schema:
|
|
type: string
|
|
- description: Filter by default view type
|
|
in: query
|
|
name: default_view
|
|
schema:
|
|
enum:
|
|
- workflow
|
|
- app
|
|
type: string
|
|
- description: Sort field
|
|
in: query
|
|
name: sort
|
|
schema:
|
|
default: create_time
|
|
enum:
|
|
- create_time
|
|
- update_time
|
|
- name
|
|
type: string
|
|
- description: Sort order
|
|
in: query
|
|
name: order
|
|
schema:
|
|
default: desc
|
|
enum:
|
|
- asc
|
|
- desc
|
|
type: string
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/WorkflowListResponse'
|
|
description: Success
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: List workflows
|
|
tags:
|
|
- workflows
|
|
post:
|
|
description: Creates a new workflow with its first version.
|
|
operationId: createWorkflow
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/CreateWorkflowRequest'
|
|
required: true
|
|
responses:
|
|
"201":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/WorkflowResponse'
|
|
description: Workflow created successfully
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"422":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Validation error
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Create a new workflow
|
|
tags:
|
|
- workflows
|
|
/api/workflows/{workflow_id}:
|
|
delete:
|
|
description: Soft-deletes a workflow.
|
|
operationId: deleteWorkflow
|
|
parameters:
|
|
- description: The UUID of the workflow to delete.
|
|
in: path
|
|
name: workflow_id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"204":
|
|
description: Workflow deleted successfully
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Workflow not found
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Delete workflow
|
|
tags:
|
|
- workflows
|
|
get:
|
|
description: Retrieves workflow metadata by ID.
|
|
operationId: getWorkflow
|
|
parameters:
|
|
- description: The UUID of the workflow.
|
|
in: path
|
|
name: workflow_id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/WorkflowResponse'
|
|
description: Success
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"403":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Forbidden
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Workflow not found
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Get workflow
|
|
tags:
|
|
- workflows
|
|
patch:
|
|
description: Updates mutable workflow metadata (name, description, default_view).
|
|
operationId: updateWorkflow
|
|
parameters:
|
|
- description: The UUID of the workflow to update.
|
|
in: path
|
|
name: workflow_id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/UpdateWorkflowRequest'
|
|
required: true
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/WorkflowResponse'
|
|
description: Success
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Workflow not found
|
|
"422":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Validation error
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Update workflow metadata
|
|
tags:
|
|
- workflows
|
|
/api/workflows/{workflow_id}/content:
|
|
get:
|
|
description: Retrieves the latest version of a workflow and its JSON content.
|
|
operationId: getWorkflowContent
|
|
parameters:
|
|
- description: The UUID of the workflow whose content should be retrieved.
|
|
in: path
|
|
name: workflow_id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/WorkflowVersionContentResponse'
|
|
description: Success
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"403":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Forbidden
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Workflow not found
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Get workflow content
|
|
tags:
|
|
- workflows
|
|
/api/workflows/{workflow_id}/fork:
|
|
post:
|
|
description: Creates a new workflow by forking from an existing version.
|
|
operationId: forkWorkflow
|
|
parameters:
|
|
- description: The UUID of the source workflow to fork from.
|
|
in: path
|
|
name: workflow_id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ForkWorkflowRequest'
|
|
required: true
|
|
responses:
|
|
"201":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/WorkflowResponse'
|
|
description: Workflow forked successfully
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"403":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Forbidden
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Source workflow or version not found
|
|
"422":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Validation error
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Fork a workflow
|
|
tags:
|
|
- workflows
|
|
/api/workflows/{workflow_id}/versions:
|
|
post:
|
|
description: Creates a new workflow version with updated workflow JSON. Uses optimistic concurrency via base_version.
|
|
operationId: createWorkflowVersion
|
|
parameters:
|
|
- description: The UUID of the workflow to create a new version for.
|
|
in: path
|
|
name: workflow_id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/CreateWorkflowVersionRequest'
|
|
required: true
|
|
responses:
|
|
"201":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/WorkflowVersionResponse'
|
|
description: Version created successfully
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"403":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Forbidden - not the workflow owner
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Workflow not found
|
|
"409":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Version conflict - base_version does not match latest
|
|
"422":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Validation error
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Create a new version
|
|
tags:
|
|
- workflows
|
|
/api/workflows/published/{share_id}:
|
|
get:
|
|
description: |
|
|
Returns the published workflow details including the status of each
|
|
published asset relative to the caller's library. Authentication is required.
|
|
operationId: getPublishedWorkflow
|
|
parameters:
|
|
- description: The share ID of the published workflow.
|
|
in: path
|
|
name: share_id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PublishedWorkflowDetail'
|
|
description: Published workflow details with asset statuses
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Share not found
|
|
"413":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Workflow JSON too large
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Get a published workflow by share ID
|
|
tags:
|
|
- workflows
|
|
/health:
|
|
get:
|
|
description: |
|
|
Returns `200 OK` if the database is reachable and dynamic config has
|
|
loaded, otherwise `503 Service Unavailable`. Used by the GKE ingress
|
|
for health checks. Response body is plain text for probe simplicity.
|
|
operationId: getHealth
|
|
responses:
|
|
"200":
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
example: OK
|
|
type: string
|
|
description: Service is healthy
|
|
"503":
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
example: Service Unavailable
|
|
type: string
|
|
description: Service is unhealthy
|
|
security: []
|
|
summary: Health probe for Kubernetes readiness/liveness
|
|
tags:
|
|
- system
|
|
/internal/folder_paths:
|
|
get:
|
|
description: Returns the filesystem paths ComfyUI loads models and assets from, keyed by folder type.
|
|
operationId: getInternalFolderPaths
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
additionalProperties:
|
|
items:
|
|
items:
|
|
type: string
|
|
type: array
|
|
type: array
|
|
description: Map of folder type name to list of path entries
|
|
type: object
|
|
description: Dictionary of folder type to paths
|
|
summary: Get configured folder paths
|
|
/internal/logs:
|
|
get:
|
|
description: Returns ComfyUI log entries from the in-memory log buffer.
|
|
operationId: getInternalLogs
|
|
responses:
|
|
"200":
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: Log text
|
|
summary: Get server logs as text
|
|
/internal/logs/raw:
|
|
get:
|
|
description: Returns the raw ComfyUI log buffer plus size metadata.
|
|
operationId: getInternalLogsRaw
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
properties:
|
|
entries:
|
|
items:
|
|
properties:
|
|
m:
|
|
description: Message
|
|
type: string
|
|
t:
|
|
description: Timestamp
|
|
type: number
|
|
type: object
|
|
type: array
|
|
size:
|
|
properties:
|
|
cols:
|
|
type: integer
|
|
rows:
|
|
type: integer
|
|
type: object
|
|
type: object
|
|
description: Structured log data
|
|
summary: Get raw structured log entries
|
|
/internal/logs/subscribe:
|
|
patch:
|
|
description: Subscribes or unsubscribes the current client from live log streaming over the WebSocket.
|
|
operationId: subscribeToLogs
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
properties:
|
|
clientId:
|
|
description: WebSocket client ID
|
|
type: string
|
|
enabled:
|
|
description: Enable or disable log streaming for this client
|
|
type: boolean
|
|
required:
|
|
- clientId
|
|
- enabled
|
|
type: object
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: Subscription updated
|
|
summary: Subscribe or unsubscribe a WebSocket client to log streaming
|
|
security:
|
|
- ApiKeyAuth: []
|
|
- BearerAuth: []
|
|
servers:
|
|
- description: Default ComfyUI server
|
|
url: /
|
|
tags:
|
|
- description: Workflow execution and management
|
|
name: workflow
|
|
- description: Node information
|
|
name: node
|
|
- description: File operations
|
|
name: file
|
|
- description: User settings management
|
|
name: settings
|
|
- description: User feedback management
|
|
name: feedback
|
|
- description: System operations and monitoring
|
|
name: system
|
|
- description: User information and management
|
|
name: user
|
|
- description: Background task management
|
|
name: task
|
|
- description: Workflow storage and version management
|
|
name: workflows
|
|
- description: Job queue state and control
|
|
name: queue
|
|
- description: Job lifecycle queries
|
|
name: job
|