English | 简体中文 | 한국어 | 日本語

MiniMax H3

Prompt Writing Skill

Install the H3 prompt writing skill — one of nine skills bundled with this repository:

npx skills add https://github.com/MiniMax-AI/MiniMax-H3 --skill h3-prompt-writing

It ships with two prompt guides under skills/h3-prompt-writing/references/: base-en.txt for text/keyframe modes and ref-en.txt for full-reference (Ref2VA) mode.

Agent compatibility: h3-prompt-writing is a plain Markdown + reference-file skill with no external API calls, so it works in Claude Code, the Claude Agent SDK, Cursor, Windsurf, OpenAI-based agents/Codex, LangChain, or any other harness that can read a SKILL.md and local files. The bundled skills/h3-prompt-writing/agents/openai.yaml only adds optional UI metadata (display name, description, default prompt) for the ChatGPT/Codex skills UI, per OpenAI’s skill spec — it does not limit the skill to OpenAI agents.

The remaining eight are style-specific video generation skills built for the MiniMax Hub’s canvas workflow (hub_generate_video, hub_generate_image, canvas nodes, choice cards, etc.) and are not portable to generic agent harnesses:

Online API

Use MiniMax-H3 directly via API.

• Global: platform.minimax.io | CN: platform.minimaxi.com

Online App

Use MiniMax-H3 directly via App.

• WebApp Global: hailuoai.video | CN: hailuoai.com
• Desktop Global: hub.minimax.io | CN: hub.minimaxi.com

System Overview

MiniMax H3 is a general-purpose, omni-modal generative system. It supports unified understanding of multimodal contexts composed of text, images, video, and audio, and can generate video with native stereo audio at resolutions up to 2K and durations of up to 15 seconds. Thanks to its task-generalization-oriented system design, H3 already possesses broad multimodal context understanding and generation capabilities at the pre-training stage, enabling outstanding performance in following complex multimodal instructions.

H3 supports the following input and output specifications:

Model Variants and Input Specifications

The complete H3 system consists of the following three modules:

• H3-Context-IR: As inputs become increasingly complex, we build a dedicated system to deeply understand and refine the input multimodal instructions, then convert them into a form that H3 can readily understand—the Context Intermediate Representation—for generation. H3-Context-IR is critical to the quality of the final output, so we strongly recommend incorporating it into your generation pipeline or following the “Prompting Guidance” to build your own context-processing system.
• H3-Base: Generates audio and video based on the H3-Context-IR output, producing results at 768p resolution.
• H3-Regenerate-2K: Feeds the 768p result together with the original context back into H3 to regenerate the output at 2K resolution. This process leverages both H3’s powerful generative capabilities and the rich information contained in the original context, enabling it to produce high-resolution outputs with more accurate details and greater visual fidelity.

Model Architecture

H3-Context-IR

H3-Context-IR is a hosted preprocessing and orchestration system designed for free-form multimodal inputs.

It interprets the relationships among text, images, audio, and reference videos, as well as how these materials relate to the intended generation output. Its internal workflow includes instruction parsing, cross-modal association, temporal understanding, and complex logical reasoning.

H3-Context-IR serializes its understanding of the context into a structured representation accepted by H3-Base. Without deviating from the user’s original intent, it may also supplement missing or underspecified semantic details where appropriate.

Because H3-Context-IR relies on a multi-stage workflow and multiple hosted models and services, it is not included in this open-source release. We provide an API that enables users to reproduce the behavior of the official workflow. We also provide detailed tutorials, and developers can follow the Prompting Guidance to build their own preprocessing systems.

For detailed usage instructions, see Recommended Workflow — Full 2K Workflow.

Safety Guardrails

User-submitted text, images and videos, as well as enhanced prompts, are subject to automated moderation. Content suspected of being unlawful, pornographic, or infringing third-party rights may be blocked. We use industry-standard filtering measures but cannot eliminate false positives or false negatives. These guardrails do not affect the Licensee’s obligations under the MiniMax H3 Community License, especially those relating to lawful use and use restrictions.

H3-Base

Architecture Overview

• H3-Base encodes different modalities using their corresponding encoders or VAEs and organizes the encoded representations into a unified packed multimodal sequence. RoPE is used to capture the necessary spatial and temporal relationships among tokens before the entire sequence is passed to the H3-Omni-Transformer.

• Specifically, text is encoded by the H3-Encoder; visual inputs are encoded by both the H3-Encoder and the H3-VisualVAE; and audio is encoded solely by the H3-AudioVAE.

• The H3-Omni-Transformer jointly predicts video and audio latents, which are then decoded into video and stereo audio, respectively.

• To reduce the computational cost of long multimodal sequences, H3 natively supports sparse-attention training and inference. The initial open-source release provides inference with full attention only. Our sparse-attention implementation will be released in a future update.

H3-Encoder

• The H3-Encoder uses the full pretrained weights of Qwen3-VL-32B and provides the hidden states from its 50th layer to the H3-Omni-Transformer.

• We add several special tokens, such as ``, to the tokenizer configuration. When using H3, the tokenizer and associated configuration files provided in the H3 repository are required.

H3-VAE

H3 uses separate visual and audio latents to represent their respective modalities.

H3-VisualVAE

• H3-VisualVAE is a temporally causal video autoencoder with a spatial compression factor of 16×, a temporal compression factor of 4×, and 24 latent channels, denoted as f16t4d24. We apply several latent-space optimization techniques to jointly improve reconstruction quality and latent learnability.

• Before being passed to the H3-Omni-Transformer, the visual latents are further patchified with a patch size of 1 × 2 × 2 along the (time, height, width) dimensions. As a result, the visual tokens entering the Transformer have an effective spatial downsampling factor of 32×, while the temporal downsampling factor remains 4×.

• The latent space of H3-VisualVAE is optimized for both reconstruction quality and ease of learning by the generative model. After training its encoder, we additionally train a ViT-based decoder to reduce decoding costs and further improve reconstruction quality.

H3-AudioVAE

• H3-AudioVAE uses the same encoder and decoder for both the left and right audio channels while processing each channel independently. The decoded channels are then recombined, enabling stereo audio input and output.
• For each channel, H3-AudioVAE compresses 32 kHz audio into a sequence of latent tokens with a temporal rate of 40 Hz.
• Inspired by VA-VAE, we optimize the latent space to preserve audio reconstruction quality while making it easier for the generative model to learn.

H3-Omni-Transformer

• For scalability and generalization, we adopt a relatively simple Transformer block design. H3-Omni-Transformer is a 33B-parameter dense, single-stream Transformer, with approximately 13B parameters residing in AdaLN-related branches. Because the AdaLN modulation outputs can be precomputed and cached, these parameters do not need to be loaded for inference-only deployment. We release the complete model weights to support further development, including fine-tuning.

• Neither the attention layers nor the FFN layers contain modality-specific structures. Modality-specific parameters are confined to the input/output layers and the AdaLN branches. In particular, modality-specific AdaLN improves generation quality with relatively low additional training and inference costs.

• The model uses three-dimensional Multimodal Rotary Position Embeddings (MM-RoPE) to represent positional relationships across the temporal and two spatial dimensions, (t, h, w).

• During the final stage of training, we introduce native sparse attention to reduce the computational cost of long sequences. The sparse-attention implementation is not included in the initial open-source release and will be published separately in a future update.

H3-Regenerate-2K

• For H3’s 2K-resolution output, instead of using a conventional dedicated super-resolution module, we use the H3 base model to regenerate its own low-resolution result through an in-context manner.

• This approach provides two advantages: (1) the regeneration process can reuse the generative capabilities of H3 base model to the greatest extent possible; and (2) the in-context format can reuse the original multimodal context when producing high-resolution output, allowing it to recover information that conventional super-resolution methods would otherwise have to “guess,” such as small text and fine details.

• In-context regeneration is also an example of task generalization.

• Due to the complexity of the system, this module is not yet open-sourced. We will release it once it is ready. We provide an API for validating the official results; see “Full 2K Workflow” below.

Recommended Workflow

To help the community deploy MiniMax H3 correctly, we provide two validation methods.

Since the complete H3 system consists of three modules—H3-Context-IR, H3-Base, and H3-Regenerate-2K—the “Full 2K Workflow” provides an end-to-end validation pipeline for 2K output, combining the Open Platform API with a locally deployed H3-Base. The “Local Deployment of H3-Base” section provides a method for validating 768p output using only a locally deployed H3-Base.

In addition, the “Prompting Guidance” section provides a detailed tutorial to help the community develop their own prompting systems.

Local Deployment of H3-Base

MiniMax H3 is released as two task-specific checkpoints. Each checkpoint contains a specialized Omni Transformer Model together with the required processor, tokenizer, text encoder, Visual VAE, and standalone Audio VAE components.

The released checkpoints are CFG-distilled Omni Transformer model weights.

Each checkpoint is distributed as a self-contained Hugging Face-style repository with the following components:

/
├── model_index.json
├── processor/
├── tokenizer/
├── text_encoder/
├── transformer/
├── visual_vae/
└── audio_vae/

Download the model. The repository hosts the original checkpoint (FL2VA/, Ref2VA/) and the diffusers format side by side, so scope the download to what your framework needs:

model_index.json is the repository-level public entry. The task-family-specific diffusers indexes remain under FL2VA/model_index.json and Ref2VA/model_index.json.

# Original checkpoint, both task families (SGLang, vLLM):
hf download MiniMaxAI/MiniMax-H3 --include "model_index.json" "FL2VA/*" "Ref2VA/*" --local-dir MiniMax-H3

# Or a single task family:
hf download MiniMaxAI/MiniMax-H3 --include "model_index.json" "FL2VA/*" --local-dir MiniMax-H3

diffusers users do not need a manual download: ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3") fetches exactly the components it needs. See the diffusers documentation for loading recipes.

We recommend the following inference frameworks to serve the model:

• SGLang - see cookbook

• vLLM - see vllm recipes

• diffusers - see diffusers docs

• ComfyUI - see Comfy tutorial; use R2V template / T2V template

Sglang Deployment

Here we use sglang as a deployment example. See the MiniMax-H3 deployment guide for additional deployment configurations.

FL2VA:

sglang serve \
  --model-path MiniMaxAI/MiniMax-H3 \
  --num-gpus 4 \
  --ulysses-degree 4 \
  --performance-mode speed \
  --host 0.0.0.0 \
  --port 30010 \
  --model-variant fl2va

Ref2VA:

sglang serve \
  --model-path MiniMaxAI/MiniMax-H3 \
  --num-gpus 4 \
  --ulysses-degree 4 \
  --performance-mode speed \
  --host 0.0.0.0 \
  --port 30011 \
  --model-variant ref2va

Reproducible 768p cases

The following three use cases T2VA, FL2VA, and Ref2VA demonstrate how to reproduce MiniMax-H3 video-audio generation.

Using a local image/video instead of a remote URL

The reproducible scripts above reference conditions[].uri values hosted on a public CDN so they work out of the box, but uri is not limited to http(s)://. For local testing you can point it at a file:// path instead — for example, to swap the FL2VA keyframe for your own image:

"conditions": [
  {
    "type": "image",
    "uri": "file:///data/minimax-h3/my-keyframe.png",
    "role": "keyframe",
    "frame_index": 0
  }
]

The path is resolved by the SGLang server process, not by the machine running curl, so it must point to a file the server can actually see:

• If sglang serve runs natively on the host, any absolute path readable by that process works.
• If it runs in a container, the file must live inside a directory you mounted into the container (e.g. mount a host folder to /data/minimax-h3 and reference file:///data/minimax-h3/...).

See the MiniMax-H3 SGLang cookbook for the full list of supported condition/media options.

Full 2K Workflow

This section explains how to combine a locally deployed SGLang service with the official H3-Context-IR and H3-Regenerate-2K APIs to reproduce the quality of 2K videos generated directly by the MiniMax API. Before you begin, configure the SGLang endpoint and your MiniMax API credentials:

# URL of your SGLang deployment
SGLANG_DEPLOYMENT_URL=""

# MiniMax API endpoint (choose one)
# CN
MINIMAX_API_BASE="https://api.minimaxi.com"
# Global
# MINIMAX_API_BASE="https://api.minimax.io"

# API token obtained from the MiniMax platform
TOKEN=""

MiniMax platform:

API docs:

• Create H3-2K: use /video-generation-v2-create EN-docs, CN-docs
• H3-Context-IR：use /video-generation-v2-h3-context-ir EN-docs, CN-docs
• H3-Regenerate-2K：use /video-generation-v2-regeneration EN-docs, CN-docs

The examples below encode local H3-Base output files as Base64 Data URLs. For production use, uploading the video to a publicly accessible URL and passing that URL as base_video is recommended.

For each case below, we provide reference outputs at both 2K and 768p generated directly through the Open Platform API, making it easier to validate the results.

case-T2VA

• Type: Text-to-video
• Duration: 10 seconds
• Aspect ratio: 16:9

case-I2VA

• Type: First-frame image-to-video
• Duration: 8 seconds
• Aspect ratio: adaptive

case-Ref2VA

• Type: Multimodal reference-to-video (video + audio)
• Duration: 5 seconds
• Aspect ratio: adaptive

Prompting Guidance

Prompting guidance documents from the HuggingFace release are not copied into this repository to keep the markdown layout minimal.

License

MiniMax H3 is released under the MiniMax H3 Community License Agreement.

Contact Us

Contact us at [email protected].