OpenAI API - Image Batch List

What it is

The other two image helpers in this pack take an existing batch and chop it up. This one does the opposite: it's a hand-fed list of image groups, one per request, where you decide what goes into each group.

That covers the workflows a splitter can't. Request one gets the front view and the side view; request two gets the front view and the back view; request three gets the texture sheet alone. Four different sets of images, four independent prompts, one queue. Or: request one gets a character reference plus pose A, request two the same reference plus pose B - comparison requests built by hand rather than by splitting a batch.

The mechanism is an autogrowing input: connect an image and a new empty slot appears after it, up to a hundred. Which is generous and, honestly, a hint that people use this node for dataset-sized jobs.

How it works

Each connected slot accepts an IMAGE of shape [H, W, C] or [B, H, W, C] and is kept intact as one entry in the list. That's the load-bearing detail: a slot holding a four-image batch contributes a single group of four images to that one request, not four groups. Splitting is the other node's job.

Slot order, not connection order, defines the list order - the execute method sorts on the numeric suffix of each input name (image_1, image_2, …) before building the list. Practically, that means the groups come out in the same left-to-right order you see on the canvas, which is what you want and is worth knowing if you've been tidying wires.

The output is a single OAIAPI_IMAGE_BATCH_LIST payload on one wire, not an execution list. Batched Chat Completion expects exactly that: one shared value it can index, paired position-by-position with the prompts list. Since the payload is one value, the "must contain exactly one shared value" check that trips on lists doesn't apply here - the whole grouping arrives as a single item.

Empty slots never exist: a slot only appears after you connect something, and an empty list raises an error rather than an empty batch. Type and shape are checked per slot, with errors that name the offending input, so a bad connection tells you which one it was.

Inputs and outputs

Images (images) - an autogrowing set of IMAGE inputs. The tooltip: "Connect images or batches; a new input appears after each connection, up to 100 inputs."

Output: Image Batches (OAIAPI_IMAGE_BATCH_LIST) → Batched Chat Completion's Image Batches input.

Install

It ships in the pack. ComfyUI Manager → search OpenAI API or Comfpod, or:

cd ComfyUI/custom_nodes
git clone https://github.com/lany42/comfyui-openai-api
cd comfyui-openai-api
/path/to/ComfyUI/.venv/bin/python -m pip install -r requirements.txt
# restart ComfyUI

Requires the openai SDK v2 (>=2.7.1,<3), numpy, Pillow, and Python 3.13+ - the pack is written against ComfyUI's newer V3 node API, so an older backend won't load it.

The pairing it implies

This node gives no Count output, and that's not an oversight - the count is however many slots you filled, and you already know that number when you wire it by hand. So the prompts side is up to you: a Multiline String to List with one line per request, or Repeat String to List with a count you set deliberately. The batch node will refuse if the two lists disagree, which is the safety net that makes hand-wiring tolerable.

Where people get burned

One slot, four images, one request. Connect a four-image batch into a single slot and the model sees all four in one message. If you wanted four separate descriptions, that's Image Batch to List, not this node.

Slots don't line up with prompts. Group three is prompt three. Inserting a new slot in the middle shifts every group after it and silently rewires which prompt goes with which image. Add slots at the end, or re-check the order before a long run.

Middle-of-the-list edits. Slots are numbered and the list is built in that order, so keep new connections at the end. If you need to drop one group from the middle of a long chain, rebuild the node from scratch rather than unpicking wires - one fewer thing to get wrong.

Image size. Nothing here resizes anything. Full-resolution images, one group at a time, straight to the endpoint - great for quality, and the reason a 20-group run can be a slow and expensive one.