🎬 ComfyUI MiniMax H3-Promptor

A powerful, node-based automation suite for generating cinema-production-grade prompts explicitly formatted for the MiniMax H3 Video Generation System.

This project provides a robust, decoupled architecture separating multimodal visual analysis from pure text-based prompt structuring, allowing for extreme customizability, precise scene description, and low API operating costs.

• Zero-Hallucination Inline Tagging: The Prompt LLM now natively embeds <Picture X> references directly inside the narrative action lines, guaranteeing 100% compliance with official MiniMax tag-binding requirements.
• Sequential Multi-Modal Processing: Upgraded the Vision Analyzer to process inputs sequentially. This eliminates Multi-Modal LLM context bleeding and guarantees proxy API limits are never exceeded.
• Flawless 6-Part Official Syntax Compliance: Our structural generation has been de-patched. The Promptor now strictly assembles the mandatory 6-part string array (subject_definitions, summary, retention, etc.) in the exact sequence HuggingFace mandates.
• Audio Pipeline Fix: Completely restored routing logic for Native Audio paths (Audio-to-Video and Image-to-Audio).
• Custom Node Theming: Added native UI coloring support for ComfyUI (appearance.js).

The pipeline consists of two nodes working in tandem to handle extreme complexity without duplicating LLM vision costs:

A highly configurable multimodal analysis engine. This node acts as your virtual Director of Photography, analyzing input imagery and video based on explicit presets.

• Infinite Dynamic Scaling: Upgraded to ComfyAPI v3 io.Autogrow. You are no longer limited to 4 images. Connect as many Images and Videos as you want seamlessly.
• Targeted Custom Overrides: Use the custom_prompt_override box to type rules like <Picture 2>: Focus entirely on the background. It will surgically override the global mode for that exact frame!
• Invisible Heavy VRAM Management: Automatically detects when you are using local models like Ollama and safely unloads them behind the scenes to preserve VRAM for the actual H3 video generation.
• Multilingual Output: Choose between English and Chinese for the analysis output language.
• Outputs: Produces a structured JSON-backed vision_context that is sent to the Promptor node, completely uncoupling image arrays from the final text pipeline.

The core structure engine. It operates at blazing speeds because it takes the user's description and the Vision Analyzer's text report to format the final H3 Prompt—meaning it does not need to repeatedly analyze heavy images.

• Intelligent Cross-Node Auto Detection: Even though this node no longer connects to images directly, the H3_Vision_Analyzer invisibly stamps a hidden [MEDIA_SIGNATURE] encoded with your exact inputs. The H3_Promptor silently parses this signature and automatically selects the correct generation mode:

• Language Selection: Output the final cinematic prompt strictly in Chinese (简体中文) or English, seamlessly bridging international setups.
• Duration Syncing: Define how long your video is (4-15s), and the LLM will rigorously pace the structural shot-list to match that exact timeframe at 24FPS.

All 4 providers are implemented as independent, native API integrations — no wrappers, no compatibility layers. Each provider file is fully self-contained for easy maintenance.

Local & Compatible APIs (LMStudio, llama.cpp, DeepSeek, etc.): Because LMStudio, llama.cpp, vLLM, and many other providers use the standard OpenAI API format, they are fully supported out of the box! Simply select OpenAI as your provider and update the "api_base" URL in your config.json to point to your local or custom endpoint (e.g., "http://localhost:1234/v1" for LMStudio). You can use any dummy string for local API keys.

Popular compatible APIs you can use with the OpenAI setting:

• DeepSeek: Highly affordable and powerful models, very popular.
• Groq: Lightning-fast inference API powered by LPU hardware.
• OpenRouter: A model aggregator platform widely used by international users.
• Together AI / SiliconFlow: APIs providing access to various open-source models (like Llama 3).

All providers support multimodal (image) inputs for the Vision Analyzer node.

Want to learn how to do Lip-Syncing, Character Interaction, Video Style Transfer, or High-End Product Commercials?

👉 Click here to view the Master Workflow Tutorials 👉 点击这里查看 8 大经典实战工作流教程 (中文版)

1. Clone the Repository: Clone this repo into your ComfyUI/custom_nodes folder:

   cd ComfyUI/custom_nodes
   git clone https://github.com/1038lab/Comfyui-Minimax-H3-Promptor.git

2. Install Dependencies:

   pip install -r requirements.txt

3. Configuration (config.json): On first load, the node will auto-create a config.json inside its folder. Open it and fill in your API keys:

   {
     "providers": {
       "openai":  { "api_key": "sk-..." },
       "gemini":  { "api_key": "AIza..." },
       "claude":  { "api_key": "sk-ant-..." }
     }
   }

   You can also override API keys directly on each node's UI without editing config.json.

Upon the first boot of V1.0.0, a vision_prompts.json file is generated in the root folder. You can open this JSON file to modify or add completely new analysis strategies:

{
    "image_prompts": {
        "Subject / Identity": "Focus exclusively on describing the main subject's appearance...",
        "Color Palette & Texture": "Focus exclusively on the dominating colors..."
    }
}

Add your own custom keys — changes take effect after a ComfyUI restart.

Want to alter how the backend formats the [SCENE] blocks? Open the templates/ directory. The system_base.txt controls global rules, while the other text files (e.g., i2v.txt) control the exact formatting structure based on the mode you selected.

• Developed by 1038lab.
• MiniMax H3 Specifications: Designed specifically to interface with the core structural requirements given by MiniMax.

GPL-3.0