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 aspartner/video/WaveSpeed, typed inputs/outputs, optional price badges, and the hidden auth/id fields needed by the shared client. Its asyncexecute()validates local media constraints, turns localIMAGE/VIDEO/AUDIO/3D inputs into hosted URLs or inline payloads, calls the provider/proxy API, then downloads or decodes the returned asset intoIO.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, andTaskResultResponse; 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/storagewithsync_op(), uploads bytes to the returned signedupload_url, and returns thedownload_urlthat 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,IMAGEtensors,VIDEOoutputs, orTypes.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
- If a provider request/response shape changes in comfy_api_nodes/…/<provider>.py, also update every constructor, extractor, and result conversion in the matching comfy_api_nodes/nodes_<provider>.py.
sync_op()andpoll_op()validate JSON through Pydantic in comfy_api_nodes/…/client.py; a field mismatch fails at runtime as a response validation error or broken extractor. - If a node sends media through URLs, keep comfy_api_nodes/nodes_<provider>.py aligned with comfy_api_nodes/…/upload_helpers.py and comfy_api_nodes/…/download_helpers.py: uploads return Comfy-hosted download URLs, while relative result URLs need the node class passed into download helpers so auth headers are attached. Passing those headers to absolute signed URLs would be wrong; client.py and download_helpers.py deliberately only apply Comfy API headers to relative paths.
- If
get_comfy_api_headers()or token renewal changes in comfy_api_nodes/…/_helpers.py, verifysync_op_raw()in comfy_api_nodes/…/client.py and relative downloads in comfy_api_nodes/…/download_helpers.py. Both callrefresh_partner_token()before authenticated Comfy API requests, but uploads to signed URLs in comfy_api_nodes/…/upload_helpers.py intentionally avoid those auth headers. - If Comfy Router semantics change, update
router_op_raw()in comfy_api_nodes/…/client.py and all provider nodes that pass model IDs such aswavespeed/flashvsrin comfy_api_nodes/nodes_wavespeed.py. Router polling mapsIN_QUEUE,IN_PROGRESS, andCOMPLETEDinto the generic poller; status-name drift silently affects progress/cancel behavior. - If a provider node's
IO.Schemahidden fields oris_api_node=Trueare removed, shared utilities that readcls.hidden.auth_token_comfy_org,cls.hidden.api_key_comfy_org,cls.hidden.unique_id, and sometimescls.hidden.dynpromptwill fail or lose auth/progress behavior. Check schemas in the changed comfy_api_nodes/nodes_*.py file and the helpers in comfy_api_nodes/…/_helpers.py together. - If price display is changed, compare static
IO.PriceBadgeexpressions in provider node schemas with server-providedX-Comfy-Credits-Usedhandling in comfy_api_nodes/…/client.py. The client gives the response header precedence for completed calls, while schemas still control pre-run estimates shown on the canvas.
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 torouter_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_USDor_COMFY_CLOUD_PRICE_BADGEchanges 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.