Reference

Reference is the most forgettable-looking node in this pack and one of the most important to understand, because it's the adapter that lets an image become a condition for Luma's Photon model. It takes an image URL and a weight, and outputs a REFERENCE object - that object is what you plug into LumaImageGeneration's style_ref, or into LumaModifyImage's modify_image_ref. Nothing in the Photon side of the pack accepts a raw URL or image tensor; everything expects a Reference. Get this one right and the whole image-reference system clicks into place.

Think of it like an IP-Adapter in the local world: a reference image carries semantic content - what things look like - and a weight controls how strongly that content steers the generation, separate from what your text prompt says. Luma's version is much simpler than IP-Adapter under the hood (it's just {"url": ..., "weight": ...} passed to their API), but the mental model transfers directly.

The inputs that matter

• image_url - a hosted image URL (the API needs publicly reachable URLs, so a local LoadImage output goes through ImgBBUpload first, or you use any CDN link).
• weight - a float from 0 to 1, default 1. This is the knob that actually matters. 1.0 is often too strong - the reference dominates and your prompt loses its voice. The example style_ref workflow uses 1.0, but for keeping a style while letting the prompt choose the subject, 0.3–0.6 is the sweet spot, the same range the KB's IP-Adapter essay recommends.

There's one output, reference of type REFERENCE.

How to use it

• Style reference: Reference → style_ref on LumaImageGeneration. The image's look transfers; the prompt drives the content.
• Edit source: Reference → modify_image_ref on LumaModifyImage. Here the weight controls how closely the edit stays anchored to the original.
• Multi-image subjects: two or more Reference nodes feed into ConcatReferences, which builds the image_ref (subject reference) for LumaImageGeneration.

Installing

It ships with the pack, so one install covers everything: ComfyUI Manager → search "ComfyUI-LumaAI-API", or git clone https://github.com/lumalabs/ComfyUI-LumaAI-API into ComfyUI/custom_nodes and install requirements.txt. No dependencies beyond the pack's standard lumaai, requests, numpy, Pillow - this node does no networking itself, it just packages the URL and weight for the API call. No API key needed here either; that lives upstream in the LumaAIClient.

Common issues

• "Where does the URL come from?" - if your image is on local disk, the chain is LoadImage → ImgBBUpload → Reference. The pack's style_ref.json and img_ref.json workflows show exactly this.
• Reference has no visible effect - weight is probably fine but the URL is failing to fetch on Luma's side, or the reference is being treated as a style when you wanted a subject (that's what ConcatReferences → image_ref is for).
• Everything looks like the reference - weight is too high. Dial it down; the prompt should still be doing real work.

It's a boring node, and that's the point. Wire a URL, set a weight, and let it be the quiet glue between your images and Luma's generation calls.