Introducing a new way to review your PRs.

Read the announcement

comfy-org / comfyui

The most powerful and modular diffusion model GUI, api and backend with a graph/nodes interface. The fastest local inference engine in the world.

View on GitHub

13 documents · Updated Nov 19, 2026

docs / comfy-api-platform

Comfy API Platform

Overview

The comfy_api/** package is the versioned API surface for newer ComfyUI extension and node authors. Its stable import points are version packages (comfy_api.v0_0_1, comfy_api.v0_0_2) plus the moving comfy_api.latest; comfy_api/version_list.py publishes those classes in ascending-version order for registry/bootstrap code. comfy_api.latest.__init__.py is the real implementation: it exports ComfyAPI, ComfyAPISync, Input, InputImpl, Types, Caching, ComfyExtension, and the public io/ui aliases. The numbered versions mostly subclass or re-export latest today: comfy_api/…/__init__.py adapts ComfyAPI_latest with VERSION = "0.0.2", while comfy_api/…/__init__.py subclasses v0_0_2 as a compatibility/template version.

comfy_api/…/_io.py is the core node schema and IO abstraction layer. The @comfytype decorator binds Python type hints and nested Input/Output classes to ComfyUI wire type strings; built-ins cover primitive widgets, tensors, model handles, audio/video, 3D assets, layer/compositor state, color/range/curve controls, and dynamic inputs. Schema is the V3 node declaration object; Schema.finalize() injects hidden auth fields for API nodes and prompt metadata fields for output nodes, then Schema.get_v1_info() translates V3 schemas into legacy class attributes (INPUT_TYPES, RETURN_TYPES, OUTPUT_NODE, etc.) consumed by existing execution paths. ComfyNode wraps define_schema() and execute() with validation, output normalization, async dispatch selection, dynamic-input expansion, hidden-value storage, and V1 compatibility properties. Node execution returns NodeOutput, or legacy tuple/dict/ExecutionBlocker values that _ComfyNodeBaseInternal.EXECUTE_NORMALIZED* normalizes into NodeOutput.

Dynamic input handling also lives in comfy_api/…/_io.py. Autogrow, DynamicCombo, DynamicSlot, and the internal _DynamicGroup register expansion functions in DYNAMIC_INPUT_LOOKUP; get_finalized_class_inputs() and parse_class_inputs() combine the static schema with live prompt inputs, recording dynamic_paths, default values, and list_paths. build_nested_inputs() later reconstructs nested dict/list structures before calling node code. This is the bridge between frontend widget names such as <group>.<index>.<field> and Python kwargs expected by a V3 node.

The input value layer is split between abstract input protocols and implementations. comfy_api/…/basic_types.py defines tensor/dict aliases for image, mask, audio, and latent values. comfy_api/…/curve_types.py and comfy_api/…/range_types.py convert raw widget payloads into evaluatable backend objects and LUTs. comfy_api/…/video_types.py defines the VideoInput protocol: components, save, trim, crop, metadata/probing, duration/frame count/rate, bit depth, color space, and stream source. Implementations in comfy_api/…/video_types.py handle disk/stream videos (VideoFromFile), tensor components (VideoFromComponents), and concatenation (VideoFromList), using PyAV for remuxing/transcoding, audio resampling, trim/crop, rotation handling, HDR/sRGB color metadata, alpha, bit depth, chroma subsampling, and memory-conscious frame materialization. comfy_api/…/video_types.py supplies VideoCodec, VideoContainer, VideoComponents, and crop normalization; comfy_api/…/geometry_types.py supplies cache-aware VOXEL, MESH, SPLAT, and File3D containers.

The UI helper layer in comfy_api/…/_ui.py creates _UIOutput payloads that node NodeOutput(ui=...) values can return. ImageSaveHelper and AudioSaveHelper save tensors to input/output/temp folders via folder_paths, preserve prompt metadata unless disabled, and wrap results in SavedImages or SavedAudios. Preview helpers (PreviewImage, PreviewMask, PreviewAudio, PreviewVideo, PreviewUI3D, PreviewUI3DAdvanced, PreviewText) serialize temporary outputs into dictionaries matching frontend expectations. _io_public.py and _ui_public.py intentionally star-export the internal modules, so public consumers import comfy_api.latest.io / IO and comfy_api.latest.ui / UI without depending on underscore paths.

comfy_api/latest.__init__.py also exposes singleton service APIs. ComfyAPI_latest.NodeReplacement.register() writes node replacement mappings into server.PromptServer.instance.node_replace_manager. ComfyAPI_latest.Execution.set_progress() updates comfy_execution.progress for the current executing node (or an explicit node_id) and converts an ImageInput tensor or PIL image into the preview tuple format used by the progress state. ComfyAPI_latest.Caching imports cache dataclasses and provider interfaces from comfy_api/…/_caching.py, then registers/unregisters providers with comfy_execution.cache_provider; providers receive CacheContext and CacheValue objects and are designed so provider exceptions do not break execution.

Sync API wrappers are generated dynamically. comfy_api/…/async_to_sync.py creates ComfyAPISync classes by wrapping async methods in a shared thread-pool event loop while copying context variables; it also wraps nested ProxiedSingleton service attributes so ComfyAPISync().execution.set_progress(...) calls the async implementation synchronously. The same module can generate .pyi files under each version's generated/ directory, and comfy_api/generate_api_stubs.py iterates supported_versions to refresh them. Existing stubs (comfy_api/latest/generated/ComfyAPISyncStub.pyi, comfy_api/v0_0_2/generated/ComfyAPISyncStub.pyi, comfy_api/v0_0_1/generated/ComfyAPISyncStub.pyi) currently describe the sync wrapper shape and ExecutionSync.set_progress().

Feature flags are centralized in comfy_api/feature_flags.py. It defines CLI-discoverable flags with typed defaults (show_signin_button, enable_telemetry, partner node controls, and local web SSO), core server capabilities (supports_preview_metadata, supports_model_type_tags, upload size, extension manager V4, node replacements, assets), connection-level accessors, and set_server_feature() for server-owned flags such as deploy_to_cloud. CLI flags are strictly coerced, unknown flags remain strings, and CLI values cannot override core or server-set capabilities.

Backward-compatible top-level imports remain for older integrations: comfy_api/…/__init__.py, comfy_api/…/__init__.py, comfy_api/util.py, and comfy_api/…/__init__.py re-export selected latest input, implementation, and utility types. comfy_api/…/torch_compile.py is a separate helper for API-facing nodes that want to attach torch.compile wrappers to a ModelPatcher at sample time.

API nodes and external integrations consume this layer by subclassing comfy_api.latest.io.ComfyNode, returning a Schema built from io.<Type>.Input / io.<Type>.Output, marking is_api_node=True when Comfy org auth/API keys and COMFY_USAGE_SOURCE are needed, and returning NodeOutput with optional ui helpers from comfy_api.latest.ui. Extension packages implement ComfyExtension.get_node_list() from comfy_api/latest.__init__.py to return those node classes; sync or async host integrations can call ComfyAPI/ComfyAPISync services for progress, node replacement, and external caching.

Routing / covers

  • Use this doc for comfy_api/**, especially comfy_api/latest/**, version adapters, feature flags, generated sync stubs, compatibility re-exports, and API-facing input/output/UI abstractions.
  • Behavioral triggers: V3 node schema authoring, API-node auth hidden fields, dynamic input expansion, NodeOutput/UI payloads, ComfyAPISync generation, video input implementations, server/client feature negotiation, and external cache-provider registration.

Coupling

  • If a type or schema shape changes in comfy_api/…/_io.py, verify both V1 compatibility properties in _ComfyNodeBaseInternal.GET_SCHEMA() and prompt parsing in get_finalized_class_inputs() / build_nested_inputs(); existing execution code reads legacy INPUT_TYPES, RETURN_TYPES, OUTPUT_IS_LIST, hidden inputs, and normalized kwargs rather than the V3 Schema object directly.
  • If adding an API-node hidden value in Hidden or HiddenHolder in comfy_api/…/_io.py, also update Schema.finalize() and HiddenHolder.from_dict() so is_api_node=True nodes receive the value without every node manually declaring it.
  • If changing dynamic input key syntax in Autogrow, DynamicCombo, DynamicSlot, or _DynamicGroup in comfy_api/…/_io.py, verify frontend prompt key generation and PriceBadgeDepends.as_dict() expectations; pricing dependencies and prompt validation use the same flattened input names.
  • If adding async service methods to ComfyAPI_latest in comfy_api/…/__init__.py, regenerate the stubs with comfy_api/generate_api_stubs.py and check comfy_api/…/async_to_sync.py; runtime sync wrappers are dynamic, but IDE/type-checker support depends on generated .pyi files.
  • If adding a new public version package, update comfy_api/version_list.py and provide a generated ComfyAPISyncStub.pyi; version discovery in comfy_api/generate_api_stubs.py uses supported_versions, not filesystem scanning.
  • If changing video codec/container behavior in comfy_api/…/video_types.py, keep VideoInput.save_to() in comfy_api/…/video_types.py and VideoCodec/VideoContainer in comfy_api/…/video_types.py aligned; callers rely on the protocol defaults, enum values, and implementation-specific remux/transcode decisions matching.
  • If changing RangeInput or CurveInput backend evaluation in comfy_api/…/range_types.py or comfy_api/…/curve_types.py, verify corresponding frontend widget math; MonotoneCubicCurve explicitly mirrors the frontend curve interpolator so backend node results match the preview.
  • If changing feature_flags.py flag names or defaults, verify CLI parsing and frontend WebSocket feature negotiation together; SERVER_FEATURE_FLAGS merges registry defaults, core capabilities, and CLI flags while preventing CLI overrides of core/server-set flags.

Risks

  • comfy_api/…/_io.py has a large compatibility boundary: schema validation, V1 class properties, dynamic input expansion, hidden-value injection, and output normalization are all co-located. If a field is renamed or omitted there, nodes can still import successfully but appear with wrong frontend metadata or receive malformed kwargs at execution time.
  • comfy_api/…/video_types.py has many format-specific branches for PyAV remux/transcode, timestamps, HEVC sample entries, WebM compatibility, color properties, alpha, trim/crop, and memory storage. If a change only tests tensor-created videos or only tests file remuxing, the other path can regress with incorrect duration, missing audio, dropped alpha, or unplayable output containers.
  • comfy_api/…/async_to_sync.py creates runtime classes by introspection and wraps nested singleton attributes. If service classes depend on constructor side effects, annotations, or non-ProxiedSingleton nested objects in a new way, ComfyAPISync may silently expose an unwrapped async object or lose type information in generated stubs.