OpenAI API - Image Batch to List

What it is

ComfyUI's IMAGE type is a batch - one tensor with a leading dimension. Wire an eight-image batch into Chat Completion and all eight images go into a single request, as eight multi-modal parts of one user message. Sometimes that's what you want. Usually it isn't: if you asked "write a caption for this image", you now have one caption describing a collage of eight.

Image Batch to List is the fork's answer. It takes an image or an image batch and produces one image group per source image - so an eight-image batch becomes eight groups, and Batched Chat Completion turns that into eight separate requests with eight separate answers, in order. Resolutions are preserved; nothing gets padded or resized to a common shape.

This is the node at the centre of the pack's actual killer workflow: a batch of reference images through a vision model, one caption each, all in one queue. That's a LoRA dataset captioning pass without a local VLM, and it's the reason someone would install this pack at all.

How it works

Each image in the input batch is unbound into its own group. Then, optionally, common images are repeated into every group - the full batch of them, in order, before or after the source image depending on mode. That's the feature that makes a workflow out of it: put a character reference sheet or a style board in Common Images, and every single request sees it alongside the image it's captioning, so all eight captions get written with the same reference in view. Prepend (common first, then the source image) is the default and reads more naturally for a model being asked to compare; append is there for when the reference should come after.

Count is the second output and it's the plumbing that keeps a batch honest: connect it into Repeat String to List's Count and your prompt count is guaranteed to match your image-group count. The pack's own README calls that wiring out.

The output is a single payload value of type OAIAPI_IMAGE_BATCH_LIST - not an execution list, deliberately. It carries the whole grouping in one wire, and because its output isn't list-typed, it arrives at the batch node as one shared value, which is exactly what that node requires.

Inputs and outputs

• Images (images) - "An image or batch; each image becomes a separate request group." Required.
• Mode (mode) - a combo, prepend or append. Where the common images go. Default prepend.
• Common Images (common_images) - optional image or batch, repeated in full for every source image.

Outputs: Image Batches (OAIAPI_IMAGE_BATCH_LIST) into Batched Chat Completion's Image Batches input, and Count (INT) into Repeat String to List.

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

Runtime dependencies are the openai SDK v2 (>=2.7.1,<3), numpy and Pillow. Python 3.13+.

Where people get burned

You forgot the images don't shrink. Each image is sent as a full-resolution base64 PNG, and with common images repeated per group the payload grows fast. Eight images plus a four-image reference sheet is 40 images' worth of vision tokens - a real bill, and a plausible timeout on the default 600-second client timeout. Resize upstream if your endpoint doesn't need the pixels.

One image, one group, or one image, one batch? A 3-image batch in, three groups out. That is the entire behaviour, and it's easy to forget when you were expecting a single request with three views.

Count wired but prompts typed. If you connect Count to Repeat String to List, that node controls the prompt count - the widget disappears from the equation. That's the point, but it does mean editing it by hand later does nothing.

Nothing in the Responses. Empty strings mean the model refused, hit a filter, or the request failed after retries. Order is preserved, so a blank at position three tells you exactly which image it was - which is the other reason to keep the order guarantee.