Add Comfy-Usage-Source pass-through for API node requests

[robinjhuang]

Captures the Comfy-Usage-Source header (or extra_data.comfy_usage_source) on POST /prompt and forwards it on API nodes' requests to api.comfy.org, defaulting to comfyui-api for direct API calls that don't identify themselves. Lets partner node API usage be attributed to the originating client. Shared outbound headers (auth, Comfy-Env, Comfy-Usage-Source) are centralized in a get_comfy_api_headers() helper — note this also adds Comfy-Env to the Sonilo streaming and relative download paths, which previously only sent auth.

API Node PR Checklist

Scope

• Is API Node Change

Pricing & Billing

• Need pricing update
• No pricing update

If Need pricing update:

• Metronome rate cards updated
• Auto‑billing tests updated and passing

QA

• QA done
• QA not required

Comms

• Informed Kosinkadink

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: c281ea07-095f-4278-b511-097405e8e86b

📥 Commits

Reviewing files that changed from the base of the PR and between ee2cdae and b8595c6.

📒 Files selected for processing (2)

• execution.py
• server.py

🚧 Files skipped from review as they are similar to previous changes (1)

• execution.py

---

📝 Walkthrough

Walkthrough

Adds a new hidden input COMFY_USAGE_SOURCE (Hidden.comfy_usage_source / comfy_usage_source) accepted by HiddenHolder and registered for API nodes. The server copies an incoming Comfy-Usage-Source request header into extra_data when missing; execution reads that into hidden inputs (V3 and legacy). get_usage_source and get_comfy_api_headers expose the value (fallback "comfyui-api"), and client, Sonilo, and cloud-download code use get_comfy_api_headers so outbound requests include a Comfy-Usage-Source header.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 46.15% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: adding Comfy-Usage-Source header pass-through for API node requests, which is the primary objective evident in the changeset.
Description check	✅ Passed	The description is directly related to the changeset, explaining how the Comfy-Usage-Source header is captured and forwarded, detailing the centralization of shared outbound headers, and documenting behavioral changes to Sonilo and download paths.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[alexisrolland]

I am concerned this could be redundant or create confusion with the Comfy-Env header because it seems there are overlapping values:

Comfy-Env:

• cloud
• cli
• local-git (which is the manual Python install)
• local-desktop
• local-portable

Comfy-Usage-Source:

• comfy-cli -> seems equivalent to Comfy-Env.cli
• comfyui-frontend -> seems covered by Comfy-Env.cloud, Comfy-Env.local-git, Comfy-Env.local-desktop, Comfy-Env.local-portable
• comfyui-server -> Not sure what this is
• comfy-mcp -> New value to be added to Comfy-Env.mcp?

What do you think @robinjhuang ?

[robinjhuang]

I am concerned this could be redundant or create confusion with the Comfy-Env header because it seems there are overlapping values:

Comfy-Env:

• cloud
• cli
• local-git (which is the manual Python install)
• local-desktop
• local-portable

Comfy-Usage-Source:

• comfy-cli -> seems equivalent to Comfy-Env.cli
• comfyui-frontend -> seems covered by Comfy-Env.cloud, Comfy-Env.local-git, Comfy-Env.local-desktop, Comfy-Env.local-portable
• comfyui-server -> Not sure what this is
• comfy-mcp -> New value to be added to Comfy-Env.mcp?

What do you think @robinjhuang ?

So usage source is the surface that the user is initiating the call from.
Env is the environment ComfyUI is installed in. So in that sense I think they are very different, despite having overlapping values. WDYT @alexisrolland ?

[alexisrolland]

I am concerned this could be redundant or create confusion with the Comfy-Env header because it seems there are overlapping values:
Comfy-Env:

• cloud
• cli
• local-git (which is the manual Python install)
• local-desktop
• local-portable

Comfy-Usage-Source:

• comfy-cli -> seems equivalent to Comfy-Env.cli
• comfyui-frontend -> seems covered by Comfy-Env.cloud, Comfy-Env.local-git, Comfy-Env.local-desktop, Comfy-Env.local-portable
• comfyui-server -> Not sure what this is
• comfy-mcp -> New value to be added to Comfy-Env.mcp?

What do you think @robinjhuang ?

So usage source is the surface that the user is initiating the call from. Env is the environment ComfyUI is installed in. So in that sense I think they are very different, despite having overlapping values. WDYT @alexisrolland ?

The definition of environment (where it's installed) vs surface (from where it's used) make sense, but then we would need to adjust the values a bit:

• Comfy-Env: we should probably remove cli which I believe is a surface?
• Comfy-Usage-Source: comfyui-server does not sound like a surface, is it for direct api calls?

I think it would make sense after adjusting the values:

Usage-Source / Env	cloud	local-git	local-desktop	local-portable
comfy-cli	✓	✓	✓	✓
comfyui-frontend	✓	✓	✓	✓
comfyui-api	✓	✓	✓	✓
comfy-mcp	✓	✗	✗	✗

[Kosinkadink]

Overall looks fine, only was able to find that Comfy-Env is not sent to everything + the manual requirement to add the header to sonilo. Adding a helper to make sure Comfy-Env + Comfy-Usage-Source will be accounted for universally would help, in case we add more headers in the future so we don't forget anything.

[Kosinkadink]

Posted by an AI agent (Amp) on behalf of @Kosinkadink.

Nice clean pass-through! One suggestion: the three outbound call sites that hit the Comfy API now build an overlapping header set by hand, and they've drifted — client.py sends auth + Comfy-Env + Comfy-Usage-Source, while nodes_sonilo.py and download_helpers.py send auth + Comfy-Usage-Source (no Comfy-Env). That divergence is exactly the kind of thing that makes the next shared header easy to forget in one spot.

Consider factoring the common set into a single helper in comfy_api_nodes/util/_helpers.py:

def get_comfy_api_headers(node_cls: type[IO.ComfyNode]) -> dict[str, str]:
    """Common headers (auth, deploy environment, usage source) for Comfy API requests.

    Centralizes these headers so every Comfy API request sends a consistent set and new
    shared headers only need to be added in one place. Intended for relative/cloud URLs
    resolved against ``default_base_url()``; because the result includes auth, callers must
    not attach it to arbitrary absolute/presigned URLs.
    """
    return {
        **get_auth_header(node_cls),
        "Comfy-Env": get_deploy_environment(),
        "Comfy-Usage-Source": get_usage_source(node_cls),
    }

Then the call sites collapse to one line each:

# client.py (relative URLs only)
payload_headers.update(get_comfy_api_headers(cfg.node_cls))

# nodes_sonilo.py
headers = get_comfy_api_headers(cls)
headers.update(endpoint.headers)

# download_helpers.py (relative 'cloud' URLs only)
headers = get_comfy_api_headers(cls)

Note this also adds Comfy-Env to the Sonilo and relative-download paths, which I think is the right call for attribution consistency since both are Comfy API control-plane requests — but it's a behavior change worth a line in the description. The helper is deliberately limited to relative/cloud paths; uploads and presigned-URL PUTs should keep going without it since it carries auth.

[robinjhuang]

I am concerned this could be redundant or create confusion with the Comfy-Env header because it seems there are overlapping values:
Comfy-Env:

• cloud
• cli
• local-git (which is the manual Python install)
• local-desktop
• local-portable

Comfy-Usage-Source:

• comfy-cli -> seems equivalent to Comfy-Env.cli
• comfyui-frontend -> seems covered by Comfy-Env.cloud, Comfy-Env.local-git, Comfy-Env.local-desktop, Comfy-Env.local-portable
• comfyui-server -> Not sure what this is
• comfy-mcp -> New value to be added to Comfy-Env.mcp?

What do you think @robinjhuang ?

So usage source is the surface that the user is initiating the call from. Env is the environment ComfyUI is installed in. So in that sense I think they are very different, despite having overlapping values. WDYT @alexisrolland ?

The definition of environment (where it's installed) vs surface (from where it's used) make sense, but then we would need to adjust the values a bit:

• Comfy-Env: we should probably remove cli which I believe is a surface?
• Comfy-Usage-Source: comfyui-server does not sound like a surface, is it for direct api calls?

I think it would make sense after adjusting the values:

Usage-Source / Env cloud local-git local-desktop local-portable
comfy-cli ✓ ✓ ✓ ✓
comfyui-frontend ✓ ✓ ✓ ✓
comfyui-api ✓ ✓ ✓ ✓
comfy-mcp ✓ ✗ ✗ ✗

Yes! Comfy-Usage-Source: comfyui-server is for direct api calls. Updated to send as comfyui-api

[robinjhuang]

@Kosinkadink Done in b58af42 — shared headers (auth, Comfy-Env, Comfy-Usage-Source) are now centralized in get_comfy_api_headers() in util/_helpers.py, and all three call sites use it. This also means the Sonilo streaming and relative download paths now send Comfy-Env too, which they previously missed — noted in the PR description.

[Kosinkadink]

nice, lgtm

[Kosinkadink]

@alexisrolland any further comments on this?