Minds · Image Candidates

What it does, and why a node exists for it

ComfyUI will happily hand you an IMAGE batch: four thumbnails from one seed sweep, four packaging variants from a prompt loop, four revisions of the same ad. What it won't hand you is names for those four things. And Minds needs names - every candidate in a preference test has a label, and the answer comes back as a distribution across those labels.

That's the entire job of this node. It takes an image batch and a JSON list of labels, pairs them up by position, and emits each image as a labelled candidate. The pack's own one-liner is accurate: it preserves order and native pixels for selection.

It is, to be blunt, a naming node. That sounds like the least interesting thing in the pack, and functionally it is. But it's also where most people's first Minds workflow dies, because the label list and the batch size have to agree exactly and nothing in the UI enforces that.

Deprecated, for the record: 0.2.2 flags this node DEPRECATED = True - the newer Minds · Audience Preferences takes images and images_b directly with a single labels_json field covering all of them. This node is the compatibility path for older workflows. Everything below is how it actually behaves, which is worth knowing even if you migrate.

How it works

images arrives as a tensor in [batch, height, width, channels], which the node checks explicitly - feed it something else and you get a clear complaint rather than a stack trace from deep inside. Then creative_labels parses your labels_json and demands the count match images.shape[0] exactly. Distinct, non-empty, 200 characters each.

Each image is detached from the graph, checked to be finite and inside [0, 1] (a decoded image, in other words - not a raw latent or an unclamped float buffer), converted to 8-bit, and saved as a PNG into a size-bounded buffer. That buffer is what gets uploaded to Minds later; the original tensor is kept alongside it as the native field on the candidate. So when a winner comes back, you get your pixels back, not a round-tripped PNG.

The buffer enforces the 50 MB local upload ceiling per image while encoding - so a freakishly large render fails at encode time rather than after a slow upload.

Inputs and outputs

images - the IMAGE batch. One node handles the whole batch; you don't need one node per image.

labels_json - a multiline string, defaulting to:

["Creative A", "Creative B"]

This has to be a JSON array whose length equals the batch size. Order is positional: element 0 names image 0. The per-node limit is 1–20 images, and the API won't take more than 20 alternatives per question anyway.

creatives - the MINDS_CREATIVES output. Wire it into Minds · Prepare Creative Test, or into a Combine if you're merging this batch with another source.

Those labels are what you'll be reading in the results. Name them for the decision, not for the file: ["Headline heavy", "Product first"] tells you what to ship next. ["v1", "v2"] is a future argument with yourself.

Install

Manager → search comfyui-minds (publisher minds), or:

cd ComfyUI/custom_nodes
git clone https://github.com/minds-ai-co/ComfyUI-Minds
cd ComfyUI-Minds && pip install -r requirements.txt

Restart ComfyUI with MINDS_API_KEY set in the server's environment. Dependencies are requests and Pillow; there are no models to download and nothing runs on your GPU. What does leave your machine is the encoded copy of every candidate - which is the deal with any node of this shape, and worth a glance at the KB's account of API-wrapper nodes before you point one at client work.

Common issues

"Creative labels must be a JSON array, in the same order as the creatives." Your label count doesn't match the batch count. Almost always a KSampler emitting 4 images against a 2-label default. Either change the batch size or list all four.

"Image values must be finite and within [0, 1]." You're feeding something that isn't a decoded image - a latent, or a tensor that took a wild math detour. Put a VAE Decode in between.

"Supply 1–20 creative candidates." More than 20 images on one node. Split the batch, or run two tests and compare results yourself - the API caps alternatives per question either way.

Labels are right in the JSON, wrong in the results. If the batch order changed upstream (a sort or an image-list shuffle), labels still map positionally. Check the batch order coming in, not the label list.

Ties come back as more winners than you asked for. That's not this node. Selection includes every candidate tied at the cutoff, deliberately, so a two-way tie at top_k=1 returns both.