HunyuanImage 3.0 Text Encode:
HunyuanImage3TextEncode prepares written descriptions for text-to-image generation with HunyuanImage 3.0. It converts human-readable language into conditioning: information that guides an image-generation model toward the scene, subjects, appearance, and visual details you describe. This is a preparation stage rather than an image generator itself, helping you connect your creative instructions to a compatible generation workflow. It also supports optional model-assisted prompt rewriting, allowing supported model variants to refine your description before encoding it. This makes the node useful both for directly expressing a carefully composed artistic brief and for working with a shorter description that you want the model to develop further.
HunyuanImage 3.0 Text Encode Input Parameters:
model
Required input of type MODEL. Supplies the model used by the HunyuanImage 3.0 encoding workflow. You should connect a compatible HunyuanImage 3.0 model rather than assuming that any connection carrying the MODEL type will work; the connection type alone does not establish compatibility with this model-specific node. The model variant also matters when you enable prompt rewriting: the supplied context identifies rewriting as supported by Instruct and Instruct-Distil variants only. No default model, numeric range, or selectable model list is defined in this node’s interface.
prompt
Required input of type STRING containing the image description you want to encode. Describe the subject, setting, composition, lighting, style, and other important visual details in natural language, for example, “A watercolor illustration of a red fox resting beneath an oak tree, soft morning light, muted autumn colors.” This text provides the creative direction for conditioning, and optional rewriting can process it before encoding. The field supports multiple lines and ComfyUI dynamic prompts. The supplied schema does not declare a default text value, a maximum text length, or a fixed list of options; it also does not establish a guaranteed token capacity for the underlying model.
width
Required input of type INT specifying the target image width supplied to the encoding process. Use it to communicate the intended horizontal image size so that text conditioning is prepared with the intended image geometry. Keep it consistent with the dimensions configured elsewhere in your generation workflow; this node does not itself produce or resize an image. The minimum is 16, the maximum is 16384, and the interface step is 16. The default is the source-code constant BASE_SIZE; its numerical value is not included in the supplied node definition. The allowed range is an interface limit, not a guarantee that every size will be practical for your model or available memory.
height
Required input of type INT specifying the target image height supplied to the encoding process. Together with width, it communicates the intended image geometry: equal values describe a square, a larger height describes a portrait format, and a larger width describes a landscape format. Match it to the height used by the rest of your generation workflow rather than treating it as an image-resizing control. The minimum is 16, the maximum is 16384, and the interface step is 16. The default is BASE_SIZE, whose numerical value is not shown in the supplied node definition. Large dimensions may be accepted by the interface while still exceeding practical generation limits.
prompt_rewriting
Optional input of type HUNYUAN_IMAGE_3_REWRITE. Accepts the configuration produced by the HunyuanImage 3.0 Prompt Rewriting node, which allows the model to rewrite your description and optionally reason about it before drawing. This can help develop a brief description, but it introduces an additional processing stage and may change the wording used for generation. The supplied context limits this feature to Instruct and Instruct-Distil models and warns that it can be slow, citing approximately one second per generated token on an RTX 4090 as an illustrative estimate rather than a guaranteed speed. When omitted, the execution method receives None. This node’s schema does not expose the rewriting configuration’s internal options or defaults, so configure those on the connected rewriting node.
custom_system_prompt
Optional input of type STRING for supplying a custom system-level instruction to the encoding workflow. A system prompt is guidance for how the model should interpret or handle the task, rather than the ordinary description of what should appear in the picture. This is an advanced customization point; the supplied code confirms that the value is passed into encoding but does not show the internal rules governing its interaction with rewriting or built-in instructions. The parameter supports multiline text and is declared with force_input=True, so it is intended to receive text through a connection. When omitted, the execution method receives None. No predefined choices, text-length limits, or built-in system-prompt text are provided in the supplied definition.
HunyuanImage 3.0 Text Encode Output Parameters:
positive
Output of type CONDITIONING containing the positive guidance prepared for the HunyuanImage 3.0 generation workflow. Conditioning is a model-readable representation rather than a readable prompt or a finished image. Its purpose is to help the downstream generation process follow the intended visual description, including any prompt rewriting applied during encoding. Connect it to the positive-conditioning input of a compatible downstream sampling or generation stage.
negative
Output of type CONDITIONING containing the negative-side conditioning prepared by the node. Compatible generation workflows can use positive and negative conditioning together when applying guidance. This node has no separate negative-prompt text input, so you should not assume that this output encodes a personal list of unwanted objects, styles, or defects. The supplied class delegates the construction of this output to the encoding implementation and does not reveal its exact contents. Connect it to the negative-conditioning input expected by your compatible downstream workflow.
rewritten_prompt
Output of type STRING exposing the prompt text returned by the encoding workflow as its rewritten-prompt result. When you enable rewriting, this provides a way to inspect the revised description, understand how your original instructions were interpreted, and preserve useful wording for later experiments. You can connect it to a compatible text-display or text-processing node. The supplied class does not show what exact value is returned when rewriting is disabled, so do not rely on it always containing either the original prompt or an empty string in that case.
HunyuanImage 3.0 Text Encode Usage Tips:
- Start with a compatible HunyuanImage 3.0 workflow and leave both optional inputs disconnected. Establish that basic text encoding and image generation work before adding rewriting or system-level customization.
- Match width and height to your intended generation dimensions. For example, 1024 × 1024 describes a square and 1280 × 768 describes a landscape layout; both follow the interface’s 16-pixel increments, but actual feasibility depends on your model and hardware.
- Write clear prompts that prioritize important visual decisions. A description such as “An editorial photograph of a ceramic vase on a wooden table, side lighting, neutral background” gives more concrete direction than a collection of vague quality terms.
- Enable prompt rewriting only with an Instruct or Instruct-Distil model. Use it when you want help developing a brief description, and leave it disconnected when you want a simpler workflow or need to avoid its additional processing time.
- Inspect rewritten_prompt when testing rewriting. Check that the revised description preserves your subject, composition, and essential details before judging the generated image.
- Leave custom_system_prompt disconnected unless you have a specific reason to customize model instructions. When experimenting with it, change one instruction at a time so you can identify which changes affect the result.
- Connect both conditioning outputs as required by your downstream workflow. The negative output is prepared by this node even though there is no editable negative-prompt field.
HunyuanImage 3.0 Text Encode Common Errors and Solutions:
Required input is missing
- Explanation: A required input such as model, prompt, width, or height has not been supplied. ComfyUI may report an input-validation error before encoding starts; the exact wording depends on your installation.
- Solution: Connect a compatible model, supply your prompt, and confirm that both dimension fields contain valid integers.
Incompatible model or missing model attribute
- Explanation: A connection may carry the MODEL type while containing a model that does not support this HunyuanImage 3.0 encoding workflow. This can lead to compatibility errors or missing-attribute errors during execution. No exact exception text is provided in the supplied source.
- Solution: Use a model loaded through the compatible HunyuanImage 3.0 workflow for your installed extension. If it still fails, check that your extension and model-loading setup are compatible versions.
Prompt rewriting fails with the selected model
- Explanation: The supplied context states that prompt rewriting is supported only by Instruct and Instruct-Distil variants. Enabling it with another variant can cause unsupported behavior or execution failure; an exact error message is not shown.
- Solution: Disconnect prompt_rewriting to test ordinary encoding, or switch to a supported Instruct or Instruct-Distil model before enabling rewriting.
Value outside the allowed range
- Explanation: Width or height is below 16 or above 16384. These values exceed the bounds declared by the node interface and may be rejected during validation.
- Solution: Set both dimensions within 16–16384 and use the interface’s 16-pixel increments. Prefer dimensions recommended for your model rather than treating the maximum as a recommended target.
Input type mismatch
- Explanation: A connected value does not match the expected input type, such as ordinary text connected to prompt_rewriting instead of a HUNYUAN_IMAGE_3_REWRITE configuration. ComfyUI may prevent the connection or reject the workflow.
- Solution: Connect prompt_rewriting to the HunyuanImage 3.0 Prompt Rewriting node’s compatible output. Supply custom_system_prompt through a STRING connection and model through a MODEL connection.
CUDA out of memory
- Explanation: This is a possible GPU runtime error, not an error string shown in the supplied node class. Model execution, optional rewriting, or the broader generation workflow may need more graphics memory than is available.
- Solution: Close other GPU-heavy applications, unload unused models where possible, and test with optional rewriting disabled. If the failure occurs during downstream image generation, reduce the generation dimensions there and update this node’s dimensions to match.
Prompt rewriting appears stuck
- Explanation: This may be slow processing rather than an error. The rewriting node’s description explicitly warns of substantial processing time, with an illustrative estimate of about one second per generated token on an RTX 4090.
- Solution: Check the execution log for continued activity and allow time for completion. For faster iterations, disconnect prompt_rewriting and first test the image description directly.
