Structured Output

The part of the pipeline that does the actual thinking

The other two nodes in ComfyUI Structured Outputs are bookkeeping. This one is the engine. You feed it the attribute schema you built with Attribute nodes, an optional prompt, and optionally an image - and it returns the values, guaranteed to match your schema instead of freeform chat text.

This is "LLM-assisted prompting turned into a node," which the community's own numbers say is mainstream now: mentions of prompt enhancers went from a dozen threads in 2023 to hundreds per year by 2026, and people stopped doing it in a browser tab and started doing it inside the graph. This pack is the minimal 3-node take on that idea, and this node is its one moving part.

How it works

The node bundles your Attribute nodes into a single pydantic model, then makes a real call to OpenAI using Instructor - a library built to force an LLM's reply into a schema. Under the hood it calls chat.completions.create with model="gpt-4o" and your schema as the response_model, so instead of a wall of prose you get back exactly {foreground}, {is_cool}, and whatever else you declared.

The image path is worth knowing about because of its privacy implications: if you connect an image, the node converts the first frame of the tensor to a base64 PNG and sends it up as a data URL in the same request. That's gpt-4o's vision talking to your screenshot, painting, or whatever's in the LoadImage. It's a cloud round-trip, and everything in that image leaves your machine.

The inputs and output that matter

• prompt (required) - a short instruction like "Analyze the image" or "Describe the foreground and background." This steers how the LLM interprets your schema.
• attributes (required) - the chain of Attribute nodes that defines what gets extracted.
• image_in (optional) - an IMAGE tensor, typically straight from LoadImage, enabling vision.

The single output is attributes (type ATTRIBUTE), which you wire into the Attribute to Text node to turn the values into a prompt - or into any node that accepts it.

Installing it and the key setup

Same install as the whole pack - Manager, or:

cd ComfyUI/custom_nodes
git clone https://github.com/tigeryy2/comfyui-structured-outputs

Then the part people miss: this node needs an OpenAI API key, and it reads it from a .env file inside the custom node folder (copy the pack's .env.example and paste your key):

cd ComfyUI/custom_nodes/comfyui-structured-outputs
cp .env.example .env   # then edit .env and set OPENAI_KEY="sk-..."

The .env goes in the pack folder, not your ComfyUI root. If it's missing, the pack logs a loud "please add a .env file with your API keys" error at startup, and the node can't run. Get a key at platform.openai.com, and remember every run spends real money.

Where people get burned

• The model is hardcoded to gpt-4o - there's no dropdown, so you can't quietly switch to gpt-4o-mini to save cash. If that matters, you're editing the source.
• Your image goes to OpenAI. Fine for personal use; a problem if you're feeding it someone else's work or anything sensitive. This is the same trust decision the community's had to make about every cloud LLM node, and it's worth a conscious yes rather than a default one.
• The requirements pin torch==2.5.1, which can fight with the torch your ComfyUI already has. If ComfyUI misbehaves after install, this is a plausible culprit - a clean venv or a newer torch is the usual fix.
• No internet, no output. Every call is a round-trip to OpenAI's API, so a network blip shows up as a failed node, not a retry.

It's a small, honest little pack with exactly one expensive habit. If you need more than three nodes' worth of LLM - local models via Ollama, agent loops, multimodal switching - you'll outgrow it fast and end up in something like LLM Party. But for "look at this image and hand me a few named variables," this is the whole job.