Ideogram - Character Edit

This node does inpainting: you supply an image, a mask marking the region to repaint, and a prompt for what fills it - plus reference images that tell it what the character looks like. The reference is the point. It's the difference between "repaint this face" and "repaint this face as her."

The friction is entirely in the mask field, and it's worth knowing before you build anything.

The mask is a URL, not a MASK socket

mask_url is a STRING. It wants the URL of an already-uploaded image file - the tooltip is explicit that it needs the file URL, not file content, and that it must match the dimensions of the input image. Accepted types are image/jpeg, image/png, image/webp, up to 10MB. The default value is a KIE-hosted sample webp, which is exactly the kind of placeholder people run by accident and then wonder why the edit landed somewhere random.

So the workflow is: draw or generate your mask, write it to disk, upload it via the pack's upload utility to get a URL, and paste (or wire) that URL into this field. ComfyUI's MASK output - from a mask editor, a SAM segmentation node, anything - does not plug in here. That's a real limitation of this node relative to a local inpaint pipeline, where the mask just flows through the graph.

Convention for masks is standard: white where you want generation, black where you want the original preserved.

image_url (required) is a proper IMAGE socket - the image being edited. reference_image_urls (required) is another IMAGE socket, holding the character references that keep the face consistent through the edit. Multiple images in the batch gives it more to work from.

prompt (required, up to 5000 characters) fills the masked area. Because the surrounding frame is fixed by the mask, this is where you describe the change - expression, angle, hair, whatever needs to differ.

The controls

rendering_speed: BALANCED (default), TURBO, QUALITY. style: AUTO, REALISTIC, FICTION - coarse, three options. expand_prompt (default true) enables MagicPrompt, Ideogram's prompt rewriter; turn it off when you want exactly what you typed. num_images is 1–4 - and note the node's image output only returns the first one; the rest live in all_urls_json. seed for reproducibility attempts, timeout_seconds (1200 default) and callback_url for plumbing.

There's no image_size on this node, which makes sense: the mask and source image dictate the frame.

Outputs

image is a native IMAGE - straight into a Save Image or a local detailer. Then url, all_urls_json, task_id, raw_json, and credits_consumed / credits_left. Results are archived to ComfyUI/output/KIE-Results/images/ with content-hashed names, so a second run doesn't overwrite the first.

Install

cd ComfyUI/custom_nodes
git clone https://github.com/felipederosilva/ComfyUI-KIE-Nodes-Next
cd ComfyUI-KIE-Nodes-Next
pip install -r requirements.txt

Restart ComfyUI. Four dependencies, no checkpoints - hosted model, so nothing lands in models/. Windows one-click installer in dist/. Manager may not list the pack; the README still frames the registry route as upcoming.

One-time key: Settings → KIE.ai Nodes Next → Connection. Validated before saving, shown only as a masked fingerprint afterwards, never written into the workflow. Servers can use KIE_API_KEY, which overrides the saved key.

Where people get burned

"The inpaint landed in the wrong place." Nine times out of ten the mask URL is the sample default, or a mask whose dimensions don't match the image. Check both before blaming the model.

Round-tripping masks is tedious. If you're doing this a lot, consider whether a local Qwen-Image-Edit pass - where the mask is just a socket - is a better fit for your workflow, and keep this node for the cases where Ideogram's text rendering or the character reference actually earns its per-call price.

Scaling the mask resizes nothing. The API needs the mask at the source image's pixel dimensions. A 1024×1024 mask over a 1536×1024 photo will be rejected or misinterpreted.

Timeout errors are already billed. The job continues server-side; recover the task_id from the error message and check it with the Task Status node.