Protoface MAI Image 2.5 · Text to Image

A very small node

This is the plainest possible shape for a paid image API: prompt, output_format, size, plus the two booking fields every Protoface node carries. No seed, no steps, no CFG, no negative prompt. Microsoft's MAI Image 2.5 does the deciding; you describe what you want and pick a shape.

That minimalism is the whole pitch and the whole limitation. You reach for this when you want a photo-real, design-ready still without standing up a checkpoint, a VAE, a text encoder and a sampler graph - a slide asset, a blog header, a mockup, a reference image to feed a local img2img pass afterwards. You don't reach for it when you want control. There are no knobs to dial, so "iterate" means "reword the prompt and pay again." Anyone who has spent an evening hunting the seed that made a good frame will find that either freeing or infuriating.

Worth saying plainly because it's the most common surprise for people arriving from local generation: nothing about this runs on your machine. No VRAM use, no model download, and no way to run it offline. It's an HTTP request with your key on it. The KB's chapter on API-wrapper nodes covers the tradeoffs properly - cost per call, inputs leaving the box, a filter you can't patch - and all of them apply here.

The inputs

prompt is doing 95% of the work, so treat it as the interface. Full sentences, concrete nouns, mention the medium if you care ("product photograph on matte grey, softbox from the left"). The node description calls the output "photoreal, design-ready," which is a fair summary of where this model is strongest - it's less of a stylist than a photographer.

output_format defaults to png. Keep it while you're working; jpg when you're producing volume.

size defaults to 1:1 and - note the name - it's the aspect ratio, not pixel dimensions. That's a trap that recurs across this pack: some nodes' size is 1280*720 pixels, this one's is a ratio. Pick from the list, don't type numbers.

generation_id (default 0) is the identity of the paid job. Leave it alone and requeueing the same inputs reuses or resumes the run; increment it and you've bought a new generation. It has nothing to do with image randomness - there's no seed field to fix, which means an identical prompt gives you a different image each call and you cannot pin the one you liked. Screenshot your winners.

request_scope is filled in automatically per node. In a headless workflow you must provide a stable unique string yourself, or submission fails with a message about a missing scope.

Outputs

image is a native IMAGE - and a list, so downstream nodes get mapped over multiple results automatically. mask comes out as a proper MASK with ComfyUI's inverted-alpha convention (mostly useful if you later build a masked refine around this result). files gives you the original downloads as PROTOFACE_FILE for Protoface Save File, which is how you keep exactly what the provider sent rather than ComfyUI's re-encode. run id is a plain string and it is the thing you paste into a support request or feed to Protoface Resume Run.

Install

ComfyUI 0.41.0 or newer, Python 3.10+, and no model files whatsoever:

cd ComfyUI/custom_nodes
git clone --branch v0.1.0 --depth 1 https://github.com/protoface-ai/protoface-comfyui.git protoface
python -m pip install -r protoface/requirements.txt

The four dependencies (httpx, jsonschema, Pillow, av>=14) are all the pack itself needs. Manager route: search Protoface, install protoface-nodes, restart ComfyUI and reload the browser. Then Protoface button, lower-right, paste key.

Where people get bitten

Nodes not appearing is nearly always version or duplication - an older ComfyUI, or the folder cloned twice under two names, which makes the entrypoint ambiguous. Check the startup log for import errors first.

"Authentication error" after a reboot is usually just the memory-only key being gone. Re-enter it.

And the recovery rule, which applies to every node in this pack: a timeout is not a lost generation. Keep generation_id, requeue or use Resume Run, and don't delete PROTOFACE_STATE_DIR - that's where the journal proving you already paid lives. Interrupting a job sends a best-effort cancel with no refund guarantee, so bailing out of a slow render is not a cheap way to experiment.