HunyuanImage 3.0 Prompt Rewriting:
HunyuanImage3PromptRewriting configures a prompt-refinement stage that lets HunyuanImage 3.0 expand your instructions into a more structured visual description before generating an image. It can request a direct rewrite or an analysis followed by a rewrite, helping the model interpret composition, subjects, lighting, materials, and image-editing instructions. The model’s rewriting guidelines emphasize preserving your core intent, expressing visual details clearly, and keeping descriptions physically and logically consistent. This node prepares the settings rather than performing the rewrite itself; the actual work happens inside a compatible HunyuanImage 3.0 encoder, where your text and any reference images are available together. In analysis-and-rewrite mode, image generation is conditioned on the complete generated sequence, including the analysis, rather than only the final rewritten description. The feature supports Instruct and Instruct-Distil models only and can be slow: the supplied node description estimates approximately one second per generated text token on an RTX 4090.
HunyuanImage 3.0 Prompt Rewriting Input Parameters:
enabled
A required BOOLEAN that controls whether prompt rewriting is used. The default is True, and the available values are True and False. When True, the node supplies rewriting settings to the connected encoder. When False, it returns no rewriting settings, so the encoder skips this stage as though the node were disconnected. Turning this off is useful for comparing your original prompt with the model-assisted version or bypassing the additional processing time without removing the node from your workflow.
mode
A required COMBO with the options rewrite only and think + rewrite; the default is rewrite only. The first option asks the model to produce the rewritten visual description directly, typically taking a few hundred tokens. The second asks it to generate an analysis before writing the revised prompt and often requires 1,000 or more tokens; this is described as the checkpoint’s own default behavior. Because image generation uses the complete generated sequence, choosing the analysis mode changes more than the text you can read afterward: the analysis also becomes part of the image-conditioning context. Use direct rewriting for a faster workflow and consider analysis-and-rewrite for requests that benefit from more interpretation, while allowing enough time and token budget for both stages.
cot_head
A required COMBO that selects the text-generation head used for rewriting. Its default is auto, and its options consist of auto plus the candidates returned by the installation’s head-discovery function; the supplied source does not provide a fixed list of those filenames. A text head is the model component that predicts the next text token during rewriting. With auto, the stage selects the file matching the loaded model, following the naming pattern hunyuan_image_3_<model>_cot_head.safetensors in models/diffusion_models. The source notes that the Instruct and Instruct-Distil heads are identical. Automatic selection is the simplest starting point; manual selection is useful when you need to explicitly choose an available compatible head.
max_new_tokens
A required INT that limits how many new text tokens the rewriting stage may generate. The default is 2048, the minimum is 1, and the maximum is 8192. Tokens are pieces of text rather than necessarily complete words, and this budget covers all generated text, including the analysis when that mode is selected. The limit is a ceiling, not a requested length: generation stops early when the rewrite is finished. A higher value gives longer requests room to complete but permits a longer run; it does not force every rewrite to use the full allowance. Setting this too low can stop generation during the analysis or midway through the rewritten prompt, leaving incomplete conditioning or no complete rewritten prompt to extract.
seed
A required INT that controls the random choices used when sampling rewritten text. The default is 0, the minimum is 0, and the maximum is 18446744073709551615, the largest unsigned 64-bit integer. Its after-generation control defaults to fixed. Keeping this seed unchanged helps you retain the same sampled rewrite while exploring different image-generation seeds, rather than unnecessarily changing the slow text-generation stage. It is separate from the seed used to generate the final image. Change it when you want to explore alternative rewritten descriptions with sampling enabled; keeping the seed fixed does not, by itself, guarantee identical behavior across different models or execution environments.
do_sample
A required BOOLEAN presented as an advanced setting, with a default of True and available values True and False. When True, the model samples its next text token from the available candidates, with the selection shaped by temperature and the probability filters. This follows the checkpoint’s stated defaults of temperature 0.6, top_p 0.95, and top_k 1024. When False, the model selects the most likely token at each step instead, making the rewriting process less varied. Turning sampling off is useful when you prefer a consistent, straightforward wording strategy; it does not guarantee that the resulting prompt will be visually better.
temperature
A required FLOAT presented as an advanced setting, with a default of 0.6, a minimum of 0.0, a maximum of 10.0, and a step of 0.01. During sampled generation, temperature adjusts how strongly the model favors likely next tokens. Lower positive values make the wording more conservative, while higher values allow more variation and can make descriptions less predictable. The default matches the checkpoint’s stated sampling configuration. If you want explicit most-likely-token generation, use do_sample=False rather than relying on a temperature of zero; although the interface permits zero, the supplied code does not establish how the downstream generator handles that boundary value.
top_p
A required FLOAT presented as an advanced setting, with a default of 0.95, a minimum of 0.0, a maximum of 1.0, and a step of 0.01. During sampling, this setting limits selection to a group of likely next tokens whose combined probability reaches the chosen threshold, a method commonly called nucleus sampling. Lower values generally narrow the available wording choices, while values closer to 1.0 permit a broader selection. It works alongside temperature and top_k rather than replacing them. The default is a sensible starting point; very restrictive values can reduce variety without necessarily improving how accurately the rewrite follows your intent.
top_k
A required INT presented as an advanced setting, with a default of 1024, a minimum of 0, and a maximum of 16384. During sampling, a positive value limits consideration to that many of the highest-ranked next-token candidates. Smaller positive values narrow the choice of words, while larger values allow a wider candidate pool, subject to the other sampling controls. The default matches the checkpoint’s stated text-generation configuration. Although the interface accepts 0, its exact downstream interpretation is not shown in the supplied source, so keep the default unless you have a specific reason to change it.
repetition_penalty
A required FLOAT presented as an advanced setting, with a default of 1.0, a minimum of 0.0, a maximum of 10.0, and a step of 0.01. This setting adjusts the tendency to reuse tokens during text generation. Under standard repetition-penalty behavior, 1.0 is neutral, values above 1.0 discourage repetition, and positive values below 1.0 can encourage it. A modest increase may help if rewrites repeat phrases unnecessarily, but an excessive penalty can also interfere with useful repetition, such as repeatedly identifying the same subject. The interface allows 0.0, but the supplied code does not confirm that the downstream generator accepts it, so the default is the safest starting point.
HunyuanImage 3.0 Prompt Rewriting Output Parameters:
prompt_rewriting
An output of type HUNYUAN_IMAGE_3_REWRITE that carries the rewriting configuration to a compatible HunyuanImage 3.0 Text Encode or Image Encode node. It contains the selected mode, text-head choice, generation budget, sampling controls, and text seed; it is not a rewritten text string or image conditioning by itself. When rewriting is disabled, the output value is None, which tells the encoder to proceed without this stage. Connect this output to the encoder’s prompt_rewriting input so rewriting can run with access to the actual prompt and, for image-based requests, the reference images. The readable rewritten_prompt is produced by the encoder afterward, not by this settings node.
HunyuanImage 3.0 Prompt Rewriting Usage Tips:
- Start with
mode=rewrite only,cot_head=auto, and the default sampling settings. This avoids the additional analysis sequence and is generally the more practical choice for everyday iteration. - Connect
prompt_rewritingto the matching input on HunyuanImage 3.0 Text Encode or Image Encode. Your original prompt belongs in the encoder, not in this settings node. - Use an Instruct or Instruct-Distil model and make sure the corresponding text-head file is available in
models/diffusion_models. Do not assume that prompt rewriting is supported by other model variants. - Keep
max_new_tokens=2048as a starting point and increase it if the logs show truncation. Forthink + rewrite, allow enough budget for both the analysis and the final description; reducing the budget aggressively can prevent the rewrite from being reached at all. - Keep the rewriting
seedfixed while testing different image seeds. This helps isolate changes in image generation from changes in the rewritten text and avoids unnecessarily invalidating the slow rewriting stage. - Treat the timing estimate seriously: at approximately one second per token on an RTX 4090, a few hundred generated tokens can take several minutes. A large token ceiling does not force a long run, but analysis-and-rewrite often generates substantially more text.
- Inspect the encoder’s
rewritten_promptbefore judging the final image. Check that important subjects, attributes, layout instructions, and any requested lettering survived the rewrite; describe text intended to appear in the image inside double quotes. - For reference-image editing, use the Image Encode workflow so the rewriting stage can consider the images together with your instructions. Specify what should change and what should remain, rather than relying only on vague requests such as “make it better.”
- Use
enabled=Falsefor a quick comparison against your original prompt. When testing the benefit of rewriting, keep other settings unchanged so the comparison is easier to interpret.
HunyuanImage 3.0 Prompt Rewriting Common Errors and Solutions:
HunyuanImage3: the rewriting budget (%d tokens) ran out before </recaption>: the image is conditioned on a partial analysis. Raise max_new_tokens, or use 'rewrite only', which skips the analysis.
- Explanation: This is a warning present in the supplied implementation; the actual token limit replaces
%din the log. The generated sequence did not reach the rewrite-start marker before the budget ran out, so image generation receives incomplete analysis instead of a completed rewrite. - Solution: Increase
max_new_tokensor switch torewrite only. If the request is unnecessarily long or repetitive, simplify it while retaining the important visual instructions.
HunyuanImage3: the rewriting budget (%d tokens) ran out inside the rewrite, so no rewritten prompt was produced. Raise max_new_tokens.
- Explanation: This warning means the rewrite began but did not reach its closing marker before the token limit was exhausted. The encoder therefore cannot extract a complete rewritten prompt.
- Solution: Raise
max_new_tokensand rerun the encoder. If you are already usingthink + rewrite, switching torewrite onlyleaves more of the available budget for the final visual description.
Missing or unavailable text-head file
- Explanation: This is a troubleshooting condition rather than a verified error string from the supplied code. Rewriting requires a compatible text head, and automatic selection expects a matching
hunyuan_image_3_<model>_cot_head.safetensorsfile inmodels/diffusion_models. - Solution: Check that the required head file is installed in the expected directory and corresponds to your loaded model. Start with
cot_head=autoor select an available compatible candidate explicitly.
Prompt rewriting does not run
- Explanation: This is a workflow symptom, not a quoted exception. The node only creates settings; no rewriting occurs if it is disabled or its output is not connected to a compatible encoder.
- Solution: Set
enabled=True, connectprompt_rewritingto the encoder’s matching input, and run the workflow through that encoder. Confirm that you are using an Instruct or Instruct-Distil model.
Unsupported model variant
- Explanation: The node description explicitly restricts rewriting to Instruct and Instruct-Distil. The supplied excerpts do not provide the exact exception message for an unsupported model.
- Solution: Load a supported model and its compatible text head, or disable rewriting when using another model variant.
Rewriting appears stuck or takes several minutes
- Explanation: Slow execution is not necessarily an error. The supplied estimate is approximately one second per token on an RTX 4090, and
think + rewriteoften produces 1,000 or more tokens. - Solution: Use
rewrite onlyfor faster iteration, keep the rewriting seed fixed when changing image seeds, and disable the stage for quick tests. Avoid lowering the token budget so far that the rewrite cannot finish.
No rewritten text appears directly on this node
- Explanation: This is expected behavior. The node outputs a settings object, not a string; the rewrite is generated later inside the connected encoder.
- Solution: Inspect the encoder’s
rewritten_promptoutput. If it is empty, check that rewriting is enabled and connected, then look for token-budget warnings.
Invalid sampling settings or text-generation failure
- Explanation: This is a possible downstream issue, not an exact error message shown in the supplied excerpts. Some interface boundaries, especially zero temperature during sampling or a zero repetition penalty, may not be accepted by the text-generation backend.
- Solution: Restore
do_sample=True,temperature=0.6,top_p=0.95,top_k=1024, andrepetition_penalty=1.0. For most-likely-token generation, setdo_sample=Falseinstead of forcing temperature to zero.
