Save 4 hours! We auto-setup your workflow! Free!

Drop your workflow.json — we handle every dependency, custom node, and model. Just open the link and run.

Auto-Setup Workflow Json (Free) Now!
ComfyUI > Nodes > ComfyUI-HunyuanImage3 > HunyuanImage 3.0 Prompt Rewriting

ComfyUI Node: HunyuanImage 3.0 Prompt Rewriting

Class Name

HunyuanImage3PromptRewriting

Category
conditioning/hunyuan image 3
Author
PedroMarinhoDev (Account age: 43days)
Extension
ComfyUI-HunyuanImage3
Latest Updated
2026-11-03
Github Stars
0.04K

How to Install ComfyUI-HunyuanImage3

Install this extension via the ComfyUI Manager by searching for ComfyUI-HunyuanImage3
  • 1. Click the Manager button in the main menu
  • 2. Select Custom Nodes Manager button
  • 3. Enter ComfyUI-HunyuanImage3 in the search bar
After installation, click the Restart button to restart ComfyUI. Then, manually refresh your browser to clear the cache and access the updated list of nodes.

Visit ComfyUI Online for ready-to-use ComfyUI environment

  • Free trial available
  • 16GB VRAM to 80GB VRAM GPU machines
  • 400+ preloaded models/nodes
  • Freedom to upload custom models/nodes
  • 200+ ready-to-run workflows
  • 100% private workspace with up to 200GB storage
  • Dedicated Support

Run ComfyUI Online

HunyuanImage 3.0 Prompt Rewriting Description

Configures HunyuanImage 3.0 prompt rewriting to expand instructions into visual descriptions.

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_rewriting to 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=2048 as a starting point and increase it if the logs show truncation. For think + 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 seed fixed 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_prompt before 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=False for 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 %d in 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_tokens or switch to rewrite 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_tokens and rerun the encoder. If you are already using think + rewrite, switching to rewrite only leaves 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.safetensors file in models/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=auto or 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, connect prompt_rewriting to 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 + rewrite often produces 1,000 or more tokens.
  • Solution: Use rewrite only for 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_prompt output. 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, and repetition_penalty=1.0. For most-likely-token generation, set do_sample=False instead of forcing temperature to zero.

HunyuanImage 3.0 Prompt Rewriting Related Nodes

Go back to the extension to check out more related nodes.
ComfyUI-HunyuanImage3
RunComfy
Copyright 2025 RunComfy. All Rights Reserved.

RunComfy is the premier ComfyUI platform, offering ComfyUI online environment and services, along with ComfyUI workflows featuring stunning visuals. RunComfy also provides AI Models, enabling artists to harness the latest AI tools to create incredible art.

HunyuanImage 3.0 Prompt Rewriting