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 / hosted-api-nodes

Hosted API Nodes (comfy_api_nodes)

Overview

comfy_api_nodes/ contains the built-in provider-backed nodes that expose hosted models and Comfy Cloud workflows as normal ComfyUI nodes. The loader in nodes.py discovers every comfy_api_nodes/nodes_*.py file with init_builtin_api_nodes() and imports it with module_parent="comfy_api_nodes"; each provider module exports async def comfy_entrypoint() returning a ComfyExtension, whose get_node_list() returns the IO.ComfyNode classes to register. For example, comfy_api_nodes/nodes_wavespeed.py defines WavespeedFlashVSRNode and WavespeedImageUpscaleNode, marks their IO.Schema with is_api_node=True, includes hidden auth fields (IO.Hidden.auth_token_comfy_org, IO.Hidden.api_key_comfy_org, IO.Hidden.unique_id), and returns those classes from WavespeedExtension.get_node_list().

The provider pattern is consistent across modules:

  • comfy_api_nodes/nodes_<provider>.py owns user-facing node schemas, validation, execution flow, uploads, API calls, and result conversion back to Comfy types. A node's define_schema() declares display name, category such as partner/video/WaveSpeed, typed inputs/outputs, optional price badges, and the hidden auth/id fields needed by the shared client. Its async execute() validates local media constraints, turns local IMAGE/VIDEO/AUDIO/3D inputs into hosted URLs or inline payloads, calls the provider/proxy API, then downloads or decodes the returned asset into IO.NodeOutput.
  • comfy_api_nodes/…/<provider>.py contains Pydantic request/response models for that provider's wire contract. For example, comfy_api_nodes/…/wavespeed.py defines FlashVSRRequest, SeedVR2ImageRequest, and TaskResultResponse; comfy_api_nodes/…/openai.py defines the image and response-model envelopes used by comfy_api_nodes/nodes_openai.py.
  • comfy_api_nodes/…/__init__.py is the public utility surface imported by node modules. It re-exports the API client operations, upload/download helpers, media conversion helpers, and validation helpers so provider modules avoid reaching into individual utility files unless they need an internal detail.

Most network traffic goes through comfy_api_nodes/…/client.py. ApiEndpoint describes an HTTP path, method, query params, and per-call headers. sync_op() / sync_op_raw() perform one request and optionally validate JSON into a Pydantic response model; poll_op() / poll_op_raw() repeatedly call a polling endpoint until a configured terminal status; router_op() / router_op_raw() submit to the Comfy Router /v2/models/{model}/requests API, poll /status, cancel on interruption, then fetch the final result. Relative endpoint paths are resolved against default_base_url() from comfy_api_nodes/…/_helpers.py, which defaults to https://api.comfy.org or the --comfy-api-base override.

Authentication and request metadata are centralized in comfy_api_nodes/…/_helpers.py. get_comfy_api_headers() adds either Authorization: Bearer <token> or X-API-KEY, plus Comfy-Env, Comfy-Usage-Source, Comfy-Core-Version, and, when available, Comfy-Job-Id. Partner-node bearer tokens are treated as renewable JWTs for the comfy-partner-node audience: refresh_partner_token() renews near expiry before a request, and renew_rejected_partner_token() allows one safe resend after comfy-api rejects a stale token with 401. These headers are only attached to relative Comfy API/proxy paths, not arbitrary absolute provider URLs.

Input/output media conventions are handled by shared helpers:

  • comfy_api_nodes/…/upload_helpers.py converts local media into Comfy-hosted download URLs. It creates upload slots through POST /customers/storage with sync_op(), uploads bytes to the returned signed upload_url, and returns the download_url that providers receive. Helpers cover batched images (upload_images_to_comfyapi()), one image, audio, video, arbitrary files, and 3D model files.
  • comfy_api_nodes/…/download_helpers.py streams result URLs to BytesIO, disk, IMAGE tensors, VIDEO outputs, or Types.File3D. Relative /proxy/... or other cloud paths require the calling node class so the helper can expand the URL against the Comfy API base and apply the shared auth headers. to_aiohttp_url() in _helpers.py preserves already-encoded signed URLs when possible.
  • comfy_api_nodes/…/conversions.py bridges Comfy tensors/files and provider-friendly bytes/base64/data-URI forms: image tensors to PIL/PNG/JPEG/WebP/base64, audio tensors to encoded containers, video inputs to base64 or resized MP4s, bytes back to image tensors/audio inputs, and video-to-frame extraction.
  • comfy_api_nodes/…/validation_utils.py provides reusable checks for image dimensions/aspect ratio, video dimensions/duration/frame count/container, audio duration, prompt string lengths, and batch size. Provider nodes call these before uploading so errors are local and specific instead of delayed until a provider rejects the request.

comfy_api_nodes/…/client.py also owns common execution behavior visible to users: per-second progress text via PromptServer.instance.send_progress_text(), Comfy ProgressBar updates for polling/estimated durations, retry/backoff handling for transient HTTP failures and rate limits, idempotency keys for non-GET Comfy API requests, friendly error messages for auth/credits/provider failures, and request/response logging through comfy_api_nodes/…/request_logger.py. Logs are written under ComfyUI's temp directory in api_logs/ and redact Authorization and X-API-KEY headers.

comfy_api_nodes/nodes_comfy_cloud.py follows the same extension and client conventions but targets Comfy Cloud workflow execution instead of a third-party provider. It builds many schemas through _cloud_schema(), starts jobs at /proxy/comfy-cloud/workflow/generate, polls /proxy/comfy-cloud/workflow/tasks/{task_id}, validates output URLs against known Cloud buckets or proxy paths, and converts returned assets with the same shared download helpers. Its API contract is modeled in comfy_api_nodes/…/comfy_cloud.py.

Routing / covers

Use this doc for changes under comfy_api_nodes/**: provider node modules (nodes_*.py), provider Pydantic contracts (apis/*.py), shared hosted-API utilities (util/*.py), and changes to how these nodes authenticate, upload/download assets, call Comfy API/proxy/provider endpoints, poll jobs, display progress/prices, or register as built-in API nodes. The only cross-area entry point this doc relies on is nodes.py:init_builtin_api_nodes(), which loads comfy_api_nodes/nodes_*.py.

Coupling

Risks

  • comfy_api_nodes/…/client.py is the retry/idempotency choke point for almost every hosted node. A change to _request_base() can turn a transient 429/5xx, a 409 idempotency-in-flight response, or an interrupted poll into duplicate provider work or an uncancellable job. Recent history shows active migration to router_op() ([Partner Nodes] feat: move more partner nodes to Comfy Router, [Partner Nodes] feat(Wan): move Wan nodes to Comfy Router, [Partner Nodes] feat(Luma): move Luma nodes to Comfy Router), so verify router submit/poll/cancel behavior whenever this file or router-backed nodes change.
  • comfy_api_nodes/nodes_comfy_cloud.py hardcodes the Comfy Cloud GPU-second list price and explicitly warns that shipping a promotional or stale lower rate can make users see less than they are charged. If COMFY_CLOUD_GPU_SECOND_USD or _COMFY_CLOUD_PRICE_BADGE changes without server-side billing verification, Comfy Cloud nodes can misquote credits indefinitely for users who keep that build.
  • comfy_api_nodes/…/download_helpers.py and comfy_api_nodes/nodes_comfy_cloud.py protect output downloads by preserving signed URL encoding and validating Comfy Cloud output buckets/proxy paths. If to_aiohttp_url() or _validated_output_url() is loosened, a provider/cloud response could redirect or point downloads outside the expected asset locations; if it is tightened incorrectly, valid signed outputs fail after the remote job has already completed.