H3 Relay · LTX Upscale Model Loader:
H3RelayLTXModelLoader, displayed as “H3 Relay · LTX Upscale Model Loader,” prepares the collection of models needed for LTX-based video enhancement in H3 Relay. It combines a diffusion model with two specialized LoRA adaptations, a video autoencoder, a learned spatial upscaler, and a text encoder into one coordinated package. The enhancement approach separates three jobs: expanding the compressed video representation to twice its spatial dimensions, adapting the diffusion model for a fast, low-step refinement schedule, and guiding that refinement with the original low-resolution video. This distinction is important because the LoRAs do not themselves perform the initial spatial expansion. The node prepares these components rather than directly generating or enlarging video, making it easier for you to configure a compatible enhancement setup without assembling each loading step individually. It also creates a configuration-based cache identifier so H3 Relay can distinguish model setups when managing reusable results.
H3 Relay · LTX Upscale Model Loader Input Parameters:
model_name
Selects the base LTX diffusion model that will receive both LoRA adaptations and perform diffusion refinement in the downstream enhancement workflow. Options come from ComfyUI’s registered diffusion_models file list, and the default is the value of the LTX_MODEL constant; its actual filename is not included in the supplied source. Choose the LTX model expected by your enhancement setup, since this node does not convert an unrelated model into a compatible LTX model. The selected filename is included in the cache identifier. This is a required dropdown selection with no numerical minimum or maximum.
vae_name
Selects the VAE, or autoencoder, included in the enhancement package. A VAE translates between visible video frames and the compressed representation, called latents, used by the diffusion workflow. Using the correct VAE matters because it must understand the latent format expected by the selected LTX model and spatial upscaler. Options come from ComfyUI’s registered vae file list, and the default is the value of LTX_VAE; the actual filename is not shown in the supplied source. The node loads and packages this component but does not itself encode or decode video. This is a required dropdown selection with no numerical minimum or maximum.
latent_2x_model_name
Selects the learned model responsible for the initial 2× spatial expansion of the video latents. This establishes the higher-resolution latent target before diffusion refinement; it is separate from both LoRAs and is the component specifically designated to perform the spatial enlargement. In spatial terms, 2× means doubling width and height, not increasing frame rate or video duration. Options come from ComfyUI’s registered latent_upscale_models file list, and the default is the value of LTX_UPSCALER; its actual filename is not provided. Select a latent upscaler compatible with the LTX setup rather than an ordinary pixel-image upscaler. This is a required dropdown selection with no numerical minimum or maximum.
text_encoder_name
Selects the text encoder packaged with the LTX model stack. A text encoder converts written prompts into a representation that the diffusion model can use in downstream processing. The node loads it using the ltxv encoder type and the default device setting, so the chosen file must be suitable for that loader configuration. Options come from ComfyUI’s registered text_encoders file list, and the default is the value of LTX_TEXT_ENCODER; its actual filename is not included in the supplied source. This node loads the encoder but does not accept or encode a prompt itself. This is a required dropdown selection with no numerical minimum or maximum.
distilled_lora
Selects the LoRA that adapts the base LTX dev transformer for a fast, low-step diffusion schedule. A LoRA is a compact set of model adjustments rather than a complete replacement model. This adaptation is applied first, before the reference-conditioned upscale LoRA, and it does not perform the 2× spatial enlargement. Options come from ComfyUI’s registered loras file list, and the default is the value of LTX_DISTILLED_LORA; its actual filename is not shown. Choose the distilled LoRA intended for your base model and downstream sampling schedule rather than an unrelated style LoRA. This is a required dropdown selection with no numerical minimum or maximum.
distilled_strength
Controls the strength of the distilled LoRA applied to the base diffusion model. The default is 1.0, the minimum is -4.0, the maximum is 4.0, and the adjustment step is 0.05. A value of 1.0 applies the LoRA at its standard scale, while 0.0 gives its model adjustments zero strength; negative values reverse the direction of those adjustments rather than providing a separate supported enhancement mode. Because this LoRA adapts the model for low-step operation, changing its strength can affect how well the model behaves with the intended refinement schedule, not simply the visual intensity of the result. The LoRA loader is still created at a strength of zero, so this setting should not be treated as a way to avoid supplying the file.
pixel_upscale_ic_lora
Selects the reference-conditioned IC-LoRA applied after the distilled LoRA. Its role is to guide diffusion using the original low-resolution pixel video after the latent representation has already been expanded by the learned 2× latent upscaler. It therefore contributes reference guidance during refinement rather than performing the initial spatial expansion. Options come from ComfyUI’s registered loras file list, and the default is the value of LTX_UPSCALE_LORA; its actual filename is not included in the supplied source. Choose the reference-conditioned upscale LoRA intended for this LTX enhancement setup. This is a required dropdown selection with no numerical minimum or maximum.
pixel_upscale_ic_strength
Controls the strength of the reference-conditioned upscale LoRA applied to the already distilled model. The default is 1.0, the minimum is 0.0, the maximum is 2.0, and the adjustment step is 0.05. Increasing this value scales up that LoRA’s model adjustments, while reducing it weakens them; the visual effect depends on the compatible model and the downstream enhancement settings, so higher values do not automatically mean better quality or more faithful detail. At 0.0, the LoRA adjustments have zero strength, but the separate 2× latent expansion component remains part of the package. The loader still references the selected LoRA file even when its strength is zero.
weight_dtype
Sets the weight-loading mode passed to the base diffusion model loader. Available options are default, fp8_e4m3fn, fp8_e4m3fn_fast, and fp8_e5m2, with default selected initially. The FP8 options use reduced-precision model weights and can help reduce weight memory requirements, but compatibility, speed, and numerical behavior depend on your hardware and software setup. The fp8_e4m3fn_fast option requests the loader’s fast FP8 mode; it is not a guarantee of faster execution on every device. This setting applies to the base diffusion model loader, not to every component in the bundle. Use default as your compatibility baseline before testing reduced-precision options.
manual_cache_revision
Provides a manual revision string that becomes part of the model stack’s cache identifier. The identifier also includes the selected component filenames, LoRA strengths, and weight-loading mode. Changing this string produces a different identifier even when those other settings remain unchanged, which is useful when you replace a model file while keeping its filename and need to distinguish the new configuration from previously cached work. It does not modify model weights or directly improve image quality. This is a required string input; its default, any special validation rules, and any length limits cannot be determined from the supplied source because the definition of _manual_cache_revision_input() is not included.
H3 Relay · LTX Upscale Model Loader Output Parameters:
ltx_model
Returns one H3_RELAY_MODEL bundle containing the LTX diffusion model with the distilled LoRA applied first and the reference-conditioned upscale LoRA applied second, together with the loaded VAE, learned latent upscaler, text encoder, and configuration cache identifier. Internally, the bundle is marked as kind ltx so the relay workflow can identify its intended role. This output represents a prepared model stack, not an enhanced video, image, latent sequence, or quality score. Connect it to a compatible H3 Relay component that expects an LTX model bundle, such as the LTX enhancement stage, rather than to a socket that expects a plain ComfyUI MODEL.
H3 Relay · LTX Upscale Model Loader Usage Tips:
- Start with a mutually compatible LTX model, VAE, text encoder, latent upscaler, and pair of LoRAs. The dropdown lists show available files, but their presence does not guarantee that they work together.
- Keep
distilled_strengthandpixel_upscale_ic_strengthat their defaults of 1.0 for your initial test. Once the workflow works, change one strength at a time using a short representative video so you can compare the effect clearly. - Keep the three enhancement roles distinct:
latent_2x_model_nameperforms spatial expansion,distilled_loraadapts the model for low-step refinement, andpixel_upscale_ic_lorasupplies reference-conditioned refinement behavior. Increasing a LoRA strength does not increase the spatial upscale factor. - Begin with
weight_dtypeset todefault. If model-weight memory is a limiting factor and your setup supports FP8, test one of the FP8 options and compare both reliability and visual results before using it for longer sequences. - Use a downstream sampling schedule appropriate for the selected distilled LoRA. This loader prepares the adaptation but does not set the sampling steps, sampler, or scheduler.
- Change
manual_cache_revisionafter replacing any selected model or LoRA file under the same filename when you need H3 Relay’s cache identity to reflect that replacement. Changing the selected filename or either LoRA strength already changes the identifier. - Place missing assets in the appropriate ComfyUI model locations or configured search paths, then refresh the model lists or restart ComfyUI as needed. The latent upscaler must appear in
latent_upscale_models, not merely in a general image-upscaler list. - Do not rely on a strength of 0.0 to bypass a missing LoRA. Both LoRA loading operations are constructed regardless of their strengths, so provide valid files for both selections.
H3 Relay · LTX Upscale Model Loader Common Errors and Solutions:
“Value not in list” for a selected model file
- Explanation: ComfyUI may report this validation error when a saved selection is no longer present in the corresponding dropdown. The file might have been moved, renamed, removed, or installed in an unregistered location. Exact wording depends on ComfyUI.
- Solution: Check the affected dropdown, install or restore the required file in the correct model location, refresh the file lists, and select an available entry. Verify all six file selections, including both LoRAs.
Model file not found or unable to open file
- Explanation: An underlying loader may fail if a selected file becomes unavailable after validation, its configured path is incorrect, or ComfyUI cannot read it. The supplied node does not define a custom error message for this situation.
- Solution: Confirm that the file exists at the registered location and is readable. If you moved or renamed it, refresh ComfyUI and select it again. A zero LoRA strength does not eliminate the need for the selected LoRA file.
Unable to determine model type or incompatible checkpoint
- Explanation: A component loader may not recognize the selected file, or the file may belong to a different model architecture. Sharing a dropdown category does not establish compatibility with LTX.
- Solution: Verify the intended architecture and loader type for every asset. Use an LTX-compatible diffusion model and matching VAE, text encoder, latent upscaler, and LoRAs. Consult the asset provider’s compatibility instructions rather than choosing files solely by similar names.
Size mismatch, shape mismatch, or LoRA weight mismatch
- Explanation: These are representative symptoms of incompatible model components, especially a LoRA trained for a different base model. Depending on the underlying loader, incompatible LoRA weights may produce warnings instead of immediately stopping execution.
- Solution: Check that both LoRAs match the selected LTX model version. Restore the intended component combination before adjusting strengths, since a lower strength does not repair incompatible weight dimensions.
FP8 operation not supported or dtype-related runtime error
- Explanation: A selected FP8 mode may be unsupported by your GPU, installed PyTorch version, or available execution backend. The precise message comes from the underlying model loader or runtime, not from this node.
- Solution: Switch
weight_dtypetodefaultand test again. If you need FP8, verify support across your hardware, ComfyUI installation, and PyTorch environment before re-enabling it.
CUDA out of memory
- Explanation: Loading or using the complete LTX stack can exceed available GPU memory. An error during subsequent enhancement can also come from the larger latents and processing workload rather than from model loading alone.
- Solution: Close other GPU-heavy applications and use ComfyUI’s appropriate memory-management settings. Consider a supported FP8 mode to reduce base-model weight memory, and reduce downstream video resolution or processing length when the failure happens during enhancement. FP8 does not reduce every source of memory use.
Error while reading model weights or checkpoint header
- Explanation: An underlying loader may encounter a damaged download, an incomplete file, or a file that is not actually a supported model checkpoint. The exact error depends on the file format and loader.
- Solution: Compare the file size or checksum with the provider’s published information when available, then download it again if necessary. Confirm that you downloaded the actual model file rather than a webpage or placeholder.
Output connection rejected because of type mismatch
- Explanation:
ltx_modelis anH3_RELAY_MODELbundle, not a plainMODEL,VAE, orCLIPoutput. Connecting it directly to a socket expecting one of those individual types is incompatible. - Solution: Connect it to the compatible H3 Relay LTX enhancement input. Use separate component loaders when building a different workflow that requires individual ComfyUI model outputs.
