JSON Chain Image Pair (Soze)

APIs that generate images from images usually want the reference picture in the request body, and a JSON payload can't hold a tensor - it can hold a base64 data URI, or a file path. JSON Chain Image Pair (Soze) is the pair node that makes a ComfyUI IMAGE a valid JSON value: it encodes a frame and adds it to your chain under the name you choose. If you're building a payload for an API node, this is how the image gets in.

It's the media-aware member of the Soze JSON family, and it solves a genuinely annoying problem: no manual base64 copying, no "save the file somewhere and hope the path matches." You wire an image in, pick a mode, and the encoding is handled. It uses the first frame of the batch - reach for the Array Pair variant if you need every frame.

How it works

Two modes, and the choice matters:

• data_uri (default) - the frame is encoded to PNG/JPEG/WebP bytes and wrapped as data:image/png;base64,.... Self-contained: the JSON is valid anywhere, no files on disk to go missing. The catch is size - the source is blunt about it: a 1MP PNG is roughly 1.5 MB of base64 text. That's a chunky payload.
• filepath - the frame is written to disk (default json_image.<ext> in ComfyUI's output directory) and the value is its absolute path. Tiny string, but the JSON is no longer self-contained - it only means something on the machine that can see that path.

format is png/jpeg/webp; jpeg_quality (default 95) only applies to jpeg and webp. In filepath mode, save_path can be relative (resolved under the output dir) or absolute, and an extension is added if missing. append_suffix (default true) appends _00001, _00002, … when the target already exists, so you never silently overwrite a file.

Inputs and outputs

• name - required string widget, the JSON key.
• image - required IMAGE input (forced). First frame of the batch is used.
• mode - data_uri or filepath.
• format - png, jpeg, or webp.
• jpeg_quality, save_path, append_suffix - filepath/quality controls, optional.
• chain_in - optional JSON_PAIRS.

Output: chain_out. A minimal chain:

Image Pair("reference", image, mode=data_uri) → JSON Generate

Installing it

Part of the Soze pack:

cd ComfyUI/custom_nodes
git clone https://github.com/SozeInc/ComfyUI_Soze.git
pip install -r ComfyUI_Soze/requirements.txt

Restart ComfyUI, or search ComfyUI_Soze in ComfyUI Manager. No models needed.

Gotchas

The big one is size. If you're hitting an API with a 10 MB data-URI payload and getting timeouts or 413s, switch to filepath mode (if the API can read local paths) or drop the image to JPEG and lower jpeg_quality. And remember it's the first frame only - pipe a batch of 12 images through this and you'll get one. For a whole batch as an array, use JSON Chain Image Array Pair, which iterates every frame. If you just need the encoded string without a key, the standalone JSON Image Encoder is the leaner tool.