Protoface Qwen Image 3.0 · Text to Image

Qwen Image 3.0 is the version of Alibaba's image model you can't download. If you've been running Qwen-Image locally since the Apache-2.0 days, the "3.0" here is the newer, closed one - stronger prompt following, better detail, no weights on HuggingFace. This node is the least painful way to get it into a ComfyUI graph.

Why bother when Z-Image and Klein exist

Fair question, and the KB's answer is that Qwen's family strength has always been instruction fidelity, not raw prettiness. Qwen-Image shipped in August 2025 as the first serious non-Western open image foundation model, best known for actually rendering text and for handling Chinese prompts without translation loss. Text-to-image on 3.0 keeps that: you describe a composition with specific objects in specific places and it mostly does what you said.

The other half of the argument is hardware. If your card can't hold a 20B MMDiT plus its Qwen2.5-VL conditioning stack, buying a few 1k images is cheaper than a new GPU. That's reason three in the standard API-node calculus: you could run a model, but not this model on this machine.

How it works under the hood

This is a generated node. Protoface bundles a JSON catalog of model/task definitions and builds a native ComfyUI V3 node for each pairing at startup - this one is alibaba/qwen-image-3.0 crossed with the image.generate operation. Every Protoface node runs the same adapter underneath; only the schema differs. That matters for troubleshooting: a broken control here behaves exactly like a broken control on the video nodes.

On queue, the adapter validates your inputs against the model's schema (before upload, before submission, before money moves), submits the job to the Protoface API, polls with a progress bar, then downloads the result into its private state directory and hands it back as real ComfyUI types. Uploads and job intents are journaled in a local SQLite file, which is what lets a requeue after a crash resume the recorded run instead of buying a second one.

Controls worth understanding

prompt is a multiline text box - the schema treats long descriptions as multiline, so expect a paragraph-capable field rather than a single line. Chinese and English both work.

resolution is 1k or 2k, defaulting to 1k. The author's own tooltip says the quiet part: it's the billing tier. Going to 2k is a real cost step, so draft at 1k.

aspect_ratio is a plain combo with fifteen options from 1:1 through 21:9 and 9:21, defaulting to 1:1. This is the one field where beginners leave money on the table - generating a 1:1 image and then outpainting it to 16:9 costs more than just choosing 16:9.

enable_prompt_expansion defaults on. It runs an LLM over your prompt and rewrites it into something richer. Keep it on for "cinematic shot of a lighthouse in fog" and turn it off the moment your prompt is a spec - a specific sign's lettering, a specific number of objects, a specific colour.

seed is optional. -1 means random; anything else is a real seed for reproducibility. And generation_id, auto-set to fixed, is the paid-job identity: leave it alone to reuse or resume, bump it to buy a fresh generation.

Outputs and what to wire them to

image is an output list - ComfyUI maps connected nodes over lists, so a single downstream Save Image or upscaler handles a batch of results without any special handling. mask is derived from the result's alpha channel with ComfyUI's inverted conventions, so it drops straight into inpaint paths. files is the original downloaded asset (PROTOFACE_FILE) - use Protoface Save File if you need the untouched file in your output folder. run id is a string: keep it, it's your handle for Protoface Resume Run and for support.

Install

Search Protoface in ComfyUI-Manager and install protoface-nodes, or do it by hand:

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

Restart, reload the browser, then click Protoface bottom-right and paste your key. Four small pure-Python dependencies (httpx, jsonschema, Pillow, av) - no torch builds, no model downloads. ComfyUI 0.41.0+ and Python 3.10+.

Traps

Restarts log you out. The interactive key lives in server memory only. Use PROTOFACE_API_KEY_FILE on a headless box.

"Protoface request_scope is missing." You're probably driving the workflow headlessly (API/script) without a scope. In the UI it's assigned automatically; from a script you must supply a stable unique string and keep it stable when resuming.

Don't delete ~/.cache/protoface-comfyui to "clean up" while a paid submission is unresolved - the journal lives there, and losing it can mean a second charge.

A model you saw announced isn't in the node list. Click Protoface → Refresh catalog, restart ComfyUI, reload the page. New models that use already-supported control types arrive this way, without updating the pack.