API429 · Edit Reference Image

Every open editing model of the last year has been measured against one target it can't touch: instruction editing on a closed model. Hand it a photo, say "keep the mug as it is, just change the background to a blue studio backdrop," and it does that - no mask, no inpaint radius, no ControlNet stack holding the subject in place. API429EditImage is how you get that motion inside a local graph: load one image, write the change, get a normal IMAGE back, keep working locally on the result.

The shape of it

Inputs are API429GenerateImage's plus one more: model, prompt, size, run_id, allow_paid_generation, optional quality - and a required image (IMAGE). That's the slot where the reference goes; a Load Image node drops straight in.

image accepts one image, and it checks. Feed it a batch and you get "Connect one reference image; split batches before this node." That's not a soft warning - split or pick before the edit node, or it won't run.

Under the hood the tensor is converted to a PNG in memory and POSTed as multipart form data to /v1/images/edits, with the file field named image. The response decodes exactly like the generate node's: base64 in, RGB tensor out, exif rotation handled.

Here's the mechanic that bites people: the run identity is a hash of the whole request, endpoint included, so your reference image is part of it. Swap the reference - or resize it, or re-export it - and you have a different request. Reuse that run_id with a different picture and the node refuses. Same ID plus identical input bytes replays the saved result for free; anything else needs a new ID and a new charge. Decide on your reference before you commit to an ID.

Prompting it

Write the change, not the picture. The shipped example gets it right: Keep the mug shape and change the background to a blue studio backdrop. These models re-emit the whole frame rather than inpainting a region, which is why they're so good at scene-level changes and why they can quietly move a face, mangle small text, or "improve" your product's logo. Check each result before using it commercially - that's not boilerplate, it's the known failure mode of the whole class.

Also: references and input tokens can add charges on top of the per-output rate, so a 24-megapixel reference feeding a 1024×1024 output buys you nothing but a bigger upload. Downscale first.

size controls the output dimensions (1024x1024, 1536x1024, 1024x1536, 2048x2048), not the input's. quality is optional and only forwarded when it isn't default. allow_paid_generation is off by default and blocks the request until you turn it on.

Install

ComfyUI Manager → search "api429", or:

cd ComfyUI/custom_nodes
git clone https://github.com/veresk06/comfyui-api429
cd comfyui-api429 && pip install -r requirements.txt

requirements.txt is numpy and Pillow - no weights, nothing to put in models/. Set the key on the server process and restart:

export API429_API_KEY="your-key-here"
python main.py

Windows portable: set the variable in the launcher environment before ComfyUI starts. The key never goes in the workflow, the prompt, or a screenshot.

There's a ready-made graph at example_workflows/edit-reference.json - start there.

Limits, and the honesty gap

This version supports one reference per edit. No masks, no inpainting, no multiple references, no URL-only result downloads. If your job is "keep this character's face" across a dozen shots, that's one run ID per shot, and the pack is not your pose or composition tool - that's still ControlNet territory on the local side.

And the part the README says out loud: the edit path has local contract tests only. No live paid verification was run for version 0.2.0; the only confirmed live call in the pack is a Nano Banana 2 text-to-image run. On top of that, the Reddit corpus through September 2026 has zero threads about API429, so there's no community war story to learn from either. Treat the first edit as a paid experiment, not a load-bearing workflow step.

Where people get burned

• "Run ID must contain 1–80 letters, digits, hyphens or underscores." The ID is validated before anything is sent. Spaces, dots and slashes all fail. edit-001 is fine; edit 001.jpg is not.
• Reuse plus a new reference = digest error. See above. New operation, new ID.
• A batch going in. The error text tells you exactly what to do: split before this node.
• "Set API429_API_KEY in the ComfyUI server environment." Set it where ComfyUI is launched, not in some other shell - and restart, because the environment is read at server start.
• An orphaned .lock in ~/.api429-comfyui. A crash can leave one and the node will tell you the run is active or was interrupted. Reconcile that run; don't nuke the state folder.