MiniMax H3 Fluxo de Trabalho do ComfyUI: Guia Completo para T2V e I2V

Executar o MiniMax H3 no ComfyUI exige adesão estrita às regras de grade espacial e temporal para evitar erros de formato de tensor, exportações MP4 silenciosas ou travamentos do modelo. O MiniMax H3 resolve esses gargalos sintetizando vídeo 2K e áudio estéreo nativo sincronizado em uma única passagem direta.

Principais Conclusões: Fluxo de Trabalho do MiniMax H3 no ComfyUI

• Passagem Multimodal Nativa: O MiniMax H3 sintetiza vídeo 2K e áudio estéreo de 32 kHz sincronizado diretamente em uma única passagem de difusão no ComfyUI.
• Limiar de Hardware: Requer no mínimo 16 GB de VRAM para execução quantizada INT8; 24 GB recomendados para renderização 2K nativa.
• Regra de Grade Espacial: As resoluções da tela e dos keyframes devem ser estritamente divisíveis por 32, ex.: 1344×768, para evitar erros de formato de tensor no VAE espacial.
• Fórmula de Grade Temporal: Os comprimentos dos clipes devem obedecer à equação Total de Quadros = 17k + 5 (5, 22, 39, 56, 141 quadros a 24 fps) para evitar truncamento latente.
• Otimização de Velocidade: Suporta uma LoRA Turbo oficial de 8 passos para reduzir os tempos de renderização em ~60% com CFG fixado em 1.0.

Enquanto o Texto-para-Vídeo (T2V) depende da inicialização latente puramente baseada em texto, o Imagem-para-Vídeo (I2V) ancora trajetórias de movimento usando nós de condicionamento first_frame, last_frame ou MiniMaxH3AddGuide. As seções a seguir detalham a configuração completa do ambiente, diagramas de conexão de nós e protocolos de solução de problemas para ambos os pipelines.

Pré-requisitos Essenciais e Estrutura de Diretórios do Modelo

Colocar um codificador de texto de 32B em models/checkpoints em vez de models/text_encoders fará com que o ComfyUI congele durante a compilação do gráfico ou falhe com um KeyError pouco útil. A maioria das falhas de configuração ocorre porque os arquivos acabam nas subpastas erradas ou porque pesos padrão do Qwen são substituídos pelo codificador de texto visual personalizado exigido pelo MiniMax H3.

Requisitos de Compatibilidade do Sistema

Antes de baixar os pesos do modelo, confirme se sua instalação atende a estas especificações básicas de hardware e ambiente:

• Núcleo do ComfyUI: Versão v0.30.0 ou superior.
• Nós Personalizados: ComfyUI-MiniMaxH3-Easy ou o pacote oficial Comfy-Org.
• VRAM da GPU: 16 GB (mín. INT8) / 24 GB (rec. 2K).
• Pilha de Software: Python 3.10+ com PyTorch 2.4+ e CUDA 12.1+.

Matriz de Posicionamento de Diretórios do Modelo

Baixe os pesos oficiais do modelo MiniMax H3 de código aberto do repositório de modelos Hugging Face e coloque cada arquivo em sua subpasta de destino designada.

Nota Crítica de Instalação

O arquivo qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors é um codificador de texto-visão quantizado AWQ de 4 bits (arquitetura Qwen3-VL) especificamente ajustado para o condicionamento de prompt do MiniMax H3. Não o substitua por transformadores de linguagem padrão na pasta text_encoders, pois modelos de linguagem genéricos carecem da projeção de visão multimodal necessária para a geração latente de vídeo.

Construindo o Gráfico de Nós do ComfyUI para Texto-para-Vídeo (T2V)

Construir um gráfico de nós limpo para Texto-para-Vídeo (T2V) no ComfyUI requer rotear embeddings de texto, configurações de resolução espacial e tensores de quadros latentes em uma sequência linear estrita.

Nota sobre Pacotes de Nós: Os nomes de nós usados ao longo deste guia de fluxo de trabalho, como MiniMaxH3TextToVideo e MiniMaxH3ImageToVideo, referem-se ao pacote personalizado ComfyUI-MiniMaxH3-Easy. Se você estiver usando o pacote oficial do Comfy-Org, essas operações são divididas em nós separados MiniMaxH3Sampler e MiniMaxH3Conditioning.

Guia Passo a Passo de Conexão de Nós T2V

Configurar a geração latente T2V requer isolar o condicionamento de texto e os parâmetros espaciais antes de executar a passagem do amostrador.

1. Conexão do Codificador de Texto: Roteie seu nó de prompt de texto para o carregador do codificador de texto-visão Qwen3-VL. Passe o tensor de saída diretamente para a porta de condicionamento de prompt positivo do nó MiniMaxH3TextToVideo.
2. Cálculo de Dimensão Espacial: Conecte os valores de saída do ResolutionSelector ao ImageScaleToTotalPixels. Esta etapa calcula a alocação de pixels enquanto impõe dimensões espaciais que permanecem divisíveis por 32.
3. Amostrador e Geração Latente: Roteie os pesos do modelo, tensores de condicionamento positivo e parâmetros de resolução diretamente para o MiniMaxH3TextToVideo para gerar o latente de vídeo bruto.
4. Decodificação VAE e Exportação de Vídeo: Envie o tensor latente através do minimax_h3_video_vae_fp16 para decodificação e, em seguida, conecte o lote de quadros renderizados diretamente ao SaveVideo.

Matriz de Roteamento de Nós T2V

Para construir este gráfico sem dependências quebradas, siga as conexões exatas das portas dos nós descritas abaixo:

O MiniMax H3 depende quase inteiramente de prompts positivos detalhados analisados pelo modelo de visão-linguagem Qwen3-VL, o que significa que nós de condicionamento negativo tradicionais adicionam carga computacional desnecessária sem melhorar a qualidade da saída. Conectar o SaveVideo diretamente ao nó de decodificação VAE de vídeo garante a renderização MP4 adequada a 24 fps sem quadros finais descartados.

Construindo o Fluxo de Trabalho de Imagem-para-Vídeo (I2V) e Primeiro/Último Quadro

Tentar animar um retrato estático ou fazer a transição entre dois keyframes geralmente resulta em distorção violenta do assunto ou travamentos imediatos de formato de tensor quando suas imagens inicial e final diferem por alguns pixels. Converter um pipeline de texto padrão em um fluxo de trabalho de Imagem-para-Vídeo (I2V) requer substituir o nó amostrador base e estabelecer pipelines de condicionamento de imagem precisos em seus quadros inicial e final.

Interpolação de Keyframe e Configuração de Nós

Para fazer a transição de T2V para geração de vídeo Primeiro-Último-Quadro (FL2V), substitua MiniMaxH3TextToVideo por MiniMaxH3ImageToVideo. Este nó expõe portas de entrada dedicadas para first_frame e last_frame, permitindo definir estados iniciais, estados finais ou transições completas de morfismo.

1. Nós LoadImage: Coloque dois nós LoadImage em sua tela para conter seus keyframes inicial e alvo.
2. Correspondência de Dimensões: Roteie as saídas de imagem através do GetImageSize para extrair as dimensões brutas de largura e altura. Isso evita incompatibilidades de grade espacial antes que os tensores entrem no amostrador.
3. Condicionamento de Tensor: Conecte os tensores de pixels processados em first_frame para animação padrão de imagem única, ou preencha ambos first_frame e last_frame para executar interpolação de keyframe.

Matriz de Conexão de Nós I2V e FL2V

O MiniMax H3 impõe paridade estrita de dimensões entre as entradas de keyframe. Ambos os keyframes devem corresponder à resolução espacial exata. Se first_frame e last_frame diferirem em tamanho, a amostragem para durante a inicialização latente. Roteie ambas as imagens através do mesmo nó de redimensionamento para garantir dimensões de pixel idênticas.

Orientação Avançada de Referência com MiniMaxH3AddGuide

Gráficos padrão de Imagem-para-Vídeo controlam apenas o primeiro e o último quadro, deixando o movimento intermediário sem ancoragem. O nó MiniMaxH3AddGuide resolve isso ancorando imagens de referência, lotes de imagens com vários quadros ou faixas de áudio em qualquer frame_idx específico ao longo da linha do tempo de geração.

Capacidades Principais do MiniMaxH3AddGuide

Como Encadear Nós de Ancoragem para Geração de Vídeo de Referência

Encadear vários nós MiniMaxH3AddGuide juntos permite a geração completa de vídeo de referência (R2V):

1. Ancoragem do Personagem Principal: Conecte seu condicionamento positivo no MiniMaxH3AddGuide com frame_idx definido como 0 para bloquear a identidade do personagem no início.
2. Keyframe de Movimento no Meio da Sequência: Encadeie um segundo nó MiniMaxH3AddGuide, alimentando uma imagem keyframe no frame_idx 60 para forçar o personagem a atingir uma pose específica no meio da cena.
3. Acoplamento de Áudio: Conecte uma trilha sonora alvo à porta de entrada de áudio e passe seu audio_vae para sincronizar o som diretamente naquele deslocamento da linha do tempo.

Encadear esses guias de condicionamento mantém a estabilidade temporal sem forçar o amostrador de difusão a reinicializar latentes.

Integrando Áudio Nativo Sincronizado com Roteamento Duplo de VAE

Os criadores passam horas alinhando manualmente trilhas de fala externas em softwares de edição de vídeo, apenas para enfrentar desvio não natural de movimento labial ou ruído ambiente incompatível. O MiniMax H3 elimina o alinhamento de áudio pós-processamento confiando na geração multimodal verdadeira, sintetizando quadros de vídeo e som estéreo de 32 kHz juntos em uma única passagem direta.

Arquitetura do Fluxo de Passagem Única

Ao contrário dos pipelines tradicionais que encadeiam modelos distintos de texto-para-fala após a renderização do vídeo, o MiniMax H3 processa dicas de texto, imagem e temporais em um espaço latente unificado. Durante a fase de remoção de ruído, o SamplerCustomAdvanced gera um payload latente composto contendo mapas de características visuais e acústicas. Essa síntese conjunta garante sincronização de diálogo precisa e geração de efeitos sonoros orgânicos alinhados precisamente com a ação na tela.

Decodificação Dupla de VAE e Configuração de Nós

Para transformar latentes brutos em mídia reproduzível, o gráfico divide a saída em dois caminhos de decodificação separados antes da multiplexação MP4.

Configuração Técnica dos Nós

1. Carregar VAEs Duplos: Adicione dois nós VAELoader distintos à sua tela. Aponte o primeiro para minimax_h3_video_vae_fp16.safetensors e o segundo para minimax_h3_audio_vae_fp32.safetensors.
2. Executar Decodificação Dupla de VAE: Roteie a saída latente visual do amostrador para o VAEDecode e o bloco de latente de áudio para o VAEDecodeAudio. Manter o minimax_h3_audio_vae_fp32 na precisão FP32 evita artefatos de clipping e distorção de frequência em trilhas sonoras de fundo.
3. Multiplexar via SaveVideo: Alimente o tensor de imagem decodificado e a forma de onda de áudio não compactada no CreateVideo ou diretamente no SaveVideo. O nó lida com a empacotamento final do contêiner, escrevendo um arquivo MP4 finalizado a 24 fps com áudio estéreo embutido.

Esta configuração nativa de fluxo duplo oferece execução de áudio com precisão de fase diretamente dentro do ComfyUI, sem exigir plugins externos de sincronização labial.

Matemática de Resolução, Restrições de Proporção de Aspecto e Ajuste de Grade de Quadros

Inserir uma resolução padrão de 1920x1080 ou definir o comprimento do clipe para 60 quadros no ComfyUI irá instantaneamente travar sua fila de renderização com um erro de formato de tensor ou deixá-lo com bordas distorcidas. O MiniMax H3 impõe limites matemáticos rígidos para dimensões espaciais e durações de clipe porque sua arquitetura VAE 3D comprime latentes de vídeo em blocos espaciais específicos e passos temporais.

Dimensões Espaciais e Predefinições de Proporção de Aspecto

O VAE espacial reduz a amostragem das entradas por um fator de 32. Se a largura ou altura alvo não for um múltiplo estrito de 32, o amostrador de difusão falha durante as alocações de tensor de limite. O modelo tem como alvo uma borda curta nativa de 768px, equilibrando fidelidade visual com seu orçamento de megapixels alvo.

Usar dimensões de pixel não padrão força o VAE a preencher ou esticar mapas de características, degradando detalhes de textura fina.

A Regra de Grade de Quadros 17k + 5

O ajuste de dimensão temporal segue uma fórmula igualmente rígida. Para permanecer dentro dos limites de comprimento de vídeo do MiniMax H3, a arquitetura processa sequências de vídeo em blocos latentes de 17 quadros com uma inicialização de cauda de 5 quadros. Para evitar truncamento temporal ou travamentos silenciosos de decodificação VAE, cada renderização deve satisfazer a equação de grade de quadros 17k + 5, onde k representa um contador inteiro de passos.

Em uma taxa de quadros padrão de 24fps, essa matemática dita durações temporais exatas:

• k = 0 (5 Quadros): ~0,21 segundos (micromovimento ou explosão estática)
• k = 1 (22 Quadros): ~0,91 segundos (fatia de ação rápida)
• k = 3 (56 Quadros): ~2,33 segundos (sequência de plano curto)
• k = 8 (141 Quadros): ~5,87 segundos (limite padrão completo do clipe)

Definir uma contagem alvo para 60 força o ComfyUI a descartar 4 quadros para 56 (k=3), desperdiçando computação VRAM durante a amostragem. Sempre ajuste os parâmetros do seu nó para o limite exato de passo 17k + 5 antes de enfileirar um lote de geração.

Otimização de Velocidade: Ativando a Execução Turbo LoRA de 8 Passos

Gastar mais de seis minutos esperando a renderização de um único vídeo de pré-visualização de 6 segundos torna a iteração rápida de prompts quase impossível em GPUs de consumo. A amostragem padrão requer de 20 a 30 passos, criando um gargalo operacional severo ao ajustar dicas de movimento, testar movimentos de câmera ou avaliar transições de keyframe.

Integrando os Pesos de Destilação Turbo

Integrar o arquivo de peso oficial minimax_h3_fl2v_turbo_8step_v1.0_comfyui_bf16 reduz as passagens de amostragem para um fluxo de trabalho de inferência de 8 passos. Este processo de destilação alcança uma otimização significativa da velocidade de geração sem comprometer a coesão visual geral.

Para configurar esta configuração de destilação no ComfyUI:

1. Coloque os Pesos do Modelo: Mova minimax_h3_fl2v_turbo_8step_v1.0_comfyui_bf16.safetensors para o diretório ComfyUI/models/loras/.
2. Conecte o Nó LoraLoader: Roteie o tensor do modelo de difusão principal através de um nó LoraLoader antes de alimentar o amostrador. Defina turbo_model_strength como 1.0.
3. Ajuste a Contagem de Passos: Reduza o parâmetro steps no seu nó MiniMaxH3Sampler do padrão de 20 para exatamente 8.
4. Bloqueie a Escala CFG: Force o parâmetro de escala de orientação livre de classificador para 1.0 para evitar saturação excessiva.

Benchmarks de Desempenho: Execução Padrão vs. Turbo

Ao executar minimax_h3_fl2v_turbo_8step, definir CFG acima de 1,0 força passagens de condicionamento duplo desnecessárias, causando queima extrema de cores, estouros de contraste e rasgos espaciais em quadros de alto movimento. Ativar turbo_mode com uma força fixa de LoRA Turbo de 1,0 permite que os criadores validem movimentos de câmera complexos em menos de três minutos antes de se comprometerem com renderizações de produção completas de 20 passos.

Solução de Problemas de Erros Comuns no Gráfico MiniMax H3 do ComfyUI

A maioria das falhas operacionais em gráficos MiniMax H3 decorre de pequenas incompatibilidades de alinhamento de tensor, decodificadores de áudio não vinculados ou gargalos de memória GPU durante o carregamento do modelo.

Guia de Diagnóstico e Correções Rápidas

1. CUDA Fora de Memória (OOM)

   1. Causa Principal: Carregar o codificador de texto de 32B junto com pesos de difusão int8 em GPUs de 16 GB de VRAM sem descarregamento de memória.
   2. Correção Passo a Passo: Adicione flags de inicialização --lowvram ou --medvram ao seu script de inicialização do ComfyUI. Para configurações de memória GPU apertadas, considere executar o MiniMax H3 no ComfyUI com quantização GGUF para reduzir os requisitos de memória base. Certifique-se de que qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors esteja estritamente dentro de models/text_encoders/, permitindo descarregamento de VRAM entre a análise de texto e as passagens de amostragem.

2. Erro de Incompatibilidade de Forma

   1. Causa Principal: Valores personalizados de largura/altura ou imagens de keyframe de entrada violam a grade de divisibilidade espacial de 32 pixels exigida.
   2. Correção Passo a Passo: Insira um nó ResolutionSelector ou ImageScaleToTotalPixels antes do amostrador para forçar todas as dimensões de tela e imagem para o múltiplo mais próximo de 32.

3. Falta de Faixa de Áudio na Exportação

   1. Causa Principal: O caminho do VAE de áudio está desvinculado ou ignorado durante a execução do gráfico.
   2. Correção Passo a Passo: Conecte minimax_h3_audio_vae_fp32 ao nó VAEDecodeAudio e, em seguida, conecte os latentes de áudio decodificados à porta de áudio do nó SaveVideo junto com o fluxo de vídeo.

4. Falha do Nó GetImageSize

   1. Causa Principal: Proporções de aspecto de keyframe incompatíveis ou lotes de imagem com vários quadros inválidos alimentados nas entradas do amostrador I2V.
   2. Correção Passo a Passo: Execute as imagens inicial e final através de um nó único ImageScaleToTotalPixels para bloquear os keyframes em dimensões idênticas antes da inicialização latente.

5. Aviso de Nós Ausentes no Gerenciador do ComfyUI

   1. Causa Principal: Pacotes de nós personalizados MiniMax H3 necessários não estão indexados ou ausentes do ambiente local.
   2. Correção Passo a Passo: Abra o Gerenciador do ComfyUI, selecione Instalar Nós Personalizados Ausentes, pesquise por ComfyUI-MiniMaxH3-Easy, clique em Instalar e reinicie o ComfyUI.

Resolvendo Quedas de Memória e Conflitos de Registro de Nós

Muitos tutoriais ignoram como o ComfyUI gerencia a alocação de VRAM em gerações consecutivas. Se você experimentar um erro repentino de CUDA Fora de Memória em uma segunda ou terceira tentativa de renderização, apesar de uma passagem inicial bem-sucedida, o ComfyUI reteve o codificador de texto na VRAM. Definir flags de descarregamento explícitas em seu script de inicialização libera a memória alocada entre as etapas do amostrador.

Ao abrir arquivos JSON da comunidade, os avisos de nós ausentes no Gerenciador do ComfyUI geralmente indicam registros de nós desatualizados. Instalar o ComfyUI-MiniMaxH3-Easy corrige essas dependências ausentes diretamente. Para pipelines I2V, resolver uma falha do GetImageSize ou um erro de incompatibilidade de forma requer garantir que as imagens de keyframe inicial e final correspondam aos limites de pixel alvo.