Protoface Asset Reference

Every Protoface model node in this pack has media inputs that can be fed two ways: a native ComfyUI socket (Image, Video, Audio) or something called References. This little utility node is what plugs into References. It takes a Protoface asset ID or a public URL and hands the model a pointer instead of a file.

Why you'd want that

Because uploads are the slow, dumb part of API generation. If you've already got a 40MB reference video sitting in the Protoface asset store - from a previous job, or from the account's asset browser - re-encoding and re-uploading it through a Load Video node on every single run is waste. Point at it once by ID and the request just names it.

Same story for anything you're iterating on. You generate a portrait in one graph, like it, and want it as the character reference in another graph twenty times. An asset ID survives that; a file path is a click-through every time.

And the third use: public URLs. The tooltip is explicit that reference accepts "an existing Protoface asset ID or public media URL", so a hosted image works without any upload at all. Handy for test fixtures, annoying for private client material.

What it does, mechanically

Almost nothing, and that's fine. The node has two inputs: reference, a plain string, and modality, a combo of image, video or audio. It validates that the string isn't blank (Supply an asset ID or public URL. if it is) and outputs a PROTOFACE_REFERENCE custom socket.

That socket carries the value plus its modality. When a model node in References mode receives it, the adapter checks the modality against what that input will accept and, if it matches, uses the reference string verbatim in the API payload - no bytes encoded, no content-hash upload, no local caching. If it doesn't match, you get a hard error rather than a silent swap: an image reference into a video field raises "Expected video reference; got image."

There is one adjacent node worth knowing about: Protoface Reuse Result Asset, which takes the files output from a Protoface run and turns it back into a reference using its asset ID. That's the chaining primitive - run A's output becomes run B's input without reuploading. If you're doing a two-stage job (generate a character, then animate it), that's the node to reach for rather than this one.

Wiring it up

1. Drop a Protoface model node that has a reference-capable input - anything with a References option, e.g. Wan 3.0 · Reference to Video or Seedance 2.0 Fast · Edit Video.
2. Set that input's mode to References.
3. Add Protoface Asset Reference, set modality to match, and connect its reference_out to the model input's reference socket.
4. If the target is a list input, items autogrow - connect one reference per slot, and remember ordering matters for prompts that say "image 1".

modality is a required dropdown with no cleverness behind it: image, video, audio. Match it to the field you're feeding, or you'll get the mismatch error described above.

Install

It ships in the same pack as everything else:

cd ComfyUI/custom_nodes
git clone --branch v0.1.0 --depth 1 https://github.com/protoface-ai/protoface-comfyui.git protoface
python -m pip install -r protoface/requirements.txt

Or install protoface-nodes from ComfyUI-Manager (search Protoface), restart ComfyUI, reload the browser. ComfyUI 0.41.0+ and Python 3.10+. The dependencies (httpx, jsonschema, Pillow, av) are for the model nodes; this one just constructs a value. You still need an API key in the Protoface panel for the model nodes to run - this node itself never calls the network.

Gotchas

A blank string is an error, not a no-op. The node raises on empty input, so don't leave it unconnected as a placeholder in a graph that will be queued.

The ID has to be yours. The tooltip says "existing Protoface asset ID"; an asset ID from someone else's account, or from a different Protoface server, resolves to nothing useful. If you're pointed at a proxy deployment via PROTOFACE_BASE_URL, the assets live with that deployment.

Deleting an asset upstream breaks a workflow quietly at queue time. The adapter re-checks cached uploads against the API and re-uploads a deleted asset - but an asset reference is just a string, so a deleted one fails at the model instead of being re-sent. If a graph that worked last month suddenly errors on a reference, check the asset still exists.

Public URLs are public. Don't use a signed URL that expires in ten minutes as a permanent reference in a workflow you'll run next week.