MiniMax-H3 README

The project's README from github.com/MiniMax-AI/MiniMax-H3. As one markdown file: README.md.

MiniMax H3

Hailuo AI API MiniMax Website GitHub Hugging Face
ModelScope MiniMax AI WeChat Discord LICENSE

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:

minimalist-product-ad-generator
minimalist-product-ad-generator		 3d-animation-short-generator
3d-animation-short-generator		 papercraft-stop-motion-explainer
papercraft-stop-motion-explainer		 brand-promo-video-generator
brand-promo-video-generator
music-video-subtitle-generator
music-video-subtitle-generator		 co-op-game-intro-generator
co-op-game-intro-generator		 paper-collage-explainer-generator
paper-collage-explainer-generator		 handdrawn-live-video-generator
handdrawn-live-video-generator

Online API

Use MiniMax-H3 directly via API.

Online App

Use MiniMax-H3 directly via App.

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:

Category Specification
Output duration 4–15 seconds
Output aspect ratio Supports a wide range of aspect ratios, including but not limited to 21:9, 16:9, 4:3, 1:1, 3:4, and 9:16
Output resolution Supports various resolution dimensions. The shorter side is set to 768 pixels by default. 2K | generation can be achieved with H3-Regenerate-2K
Output frame rate 24 FPS
Output audio 32 kHz stereo
Supported dialogue languages Stable support for 11 languages: Arabic, Chinese, English, French, German, Italian, Japanese, Korean, Portuguese, Russian, and Spanish. Additional languages are also supported to varying degrees

Model Variants and Input Specifications

Model Variant Input Mode Specifications
H3-Base-FL2VA First-and-last-frame mode Supports zero, one, or two input images.

- No image input: Text-to-video mode
- One image input: First-frame-to-video or last-frame-to-video generation
- Two image inputs: First-and-last-frame-to-video generation
H3-Base-Ref2VA Omni-reference mode Supports multi-modal reference inputs:

- Images: ≤ 9 images
- Videos: ≤ 3 clips; each clip must be 2–15 seconds long; total duration ≤ 15 seconds
- Audio: ≤ 3 clips; each clip must be 2–15 seconds long; total duration ≤ 15 seconds
- Mixed inputs: Maximum number of files across all input types is 12

Image

The complete H3 system consists of the following three modules:

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

Image

Architecture Overview

H3-Encoder

H3-VAE

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

H3-VisualVAE
H3-AudioVAE

H3-Omni-Transformer

H3-Regenerate-2K

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.

Checkpoint Supported Tasks Input Conditions Output Precision
MiniMax-H3 Base FL2VA Text-to-Audio-Video (t2va), First/Last-Frame-to-Audio-Video (fl2va) Text; optional first frame, last frame, or both Video and audio BF16
MiniMax-H3 Base Ref2VA Reference-to-Audio-Video (ref2va) Text with reference images, videos, and/or audio Video and audio BF16

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:

<TASK>/
├── 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 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.

Use case Request Result
T2VA View script t2va.mp4
FL2VA View script

MiniMax-H3 (MiniMax-AI/MiniMax-H3)

Searching Database…

10.1K ·GitHub
MiniMax-H3
Что это такое?MiniMax H3 — универсальная омнимодальная генеративная система: она принимает смешанный ввод из текста, изображений, видео и аудио и генерирует видео с нативным стереозвуком, с разрешением до 2K и длительностью до 15 секунд на клип.
То есть что я на самом деле получу, когда склонирую репозиторий — всю систему целиком?Только основной генератор: в репозитории H3-Base поставляется в виде двух чекпоинтов под конкретные задачи плюс девять агентских навыков (skills). Стадия предобработки Context-IR и модуль регенерации в 2K закрыты — их поведение покрыто API.
Где мне вообще его запустить — в облачном приложении, через API или на своей машине?Быстрее всего в облаке: веб-приложение hailuoai.video, десктопный hub.minimax.io или API на platform.minimax.io (для всех трёх есть китайские зеркала). Для локального запуска разверните открытые чекпоинты H3-Base по разделу Local Deployment в README.
Какие ограничения у клипов, которые она создаёт?Клипы идут от 4 до 15 секунд при 24 FPS со стереозвуком 32 кГц; вывод по умолчанию — 768p (по короткой стороне), с возможностью апгрейда до 2K через отдельный проход H3-Regenerate-2K. Соотношения сторон — от 21:9 и 16:9 до 1:1 и 9:16.
Есть ли модерация того, что я отправляю?Да — отправляемый текст, изображения, видео и улучшенные промпты проходят автоматическую модерацию; контент, распознанный как противоправный, порнографический или нарушающий чужие права, может быть заблокирован, причём ложные срабатывания возможны.
Могу ли я свободно использовать веса — что говорит лицензия?Действует MiniMax H3 Community License — это специальная лицензия, а не стандартная open-source (в метаданных GitHub никакая не указана). В README подчёркивается, что модерация не снимает с вас обязанностей использовать модель на законных основаниях согласно этой лицензии.
Могу ли я запустить открытые чекпоинты на своём железе?Требования к оборудованию не указаны, но H3-Base — это плотный трансформер на 33 млрд параметров, причём около 13 млрд из них (ветки AdaLN) можно пропустить на инференсе. Всё равно это не модель для ноутбука — рассчитывайте на серьёзный объём видеопамяти.
Что можно подать на вход, кроме текстового промпта?Два режима ввода: H3-Base-FL2VA принимает ноль, одну или две картинки (чистый text-to-video, по первому или последнему кадру, либо по первому и последнему кадру). H3-Base-Ref2VA принимает смешанные референсы: до 9 изображений, 3 видеоклипов и 3 аудиоклипов — всего 12 файлов.
Что такое H3-Context-IR?Это облачный сервис предобработки: он разбирает ваш промпт и референс-медиа, рассуждает между модальностями и переписывает всё в структурированное Context Intermediate Representation, из которого генерирует H3-Base. Он с закрытым исходным кодом — либо вызывайте его API, либо следуйте Prompting Guidance, чтобы собрать своё.
Как работает вывод в 2K?Это не классическое super-resolution: H3-Regenerate-2K подаёт результат в 768p вместе с исходным контекстом обратно в модель и регенерирует уже в 2K, восстанавливая мелкие детали, а не угадывая их. Модуль пока не открыт — API валидирует официальный сценарий работы.
Что за девять встроенных навыков?Один — h3-prompt-writing, переносимый Markdown-навык с двумя гайдами по промптам, который работает в Claude Code, Claude Agent SDK, Cursor, Windsurf, Codex и LangChain. Остальные восемь — генераторы под конкретные стили для канваса MiniMax Hub — реклама товаров, короткие 3D-мультфильмы, покерфт-объяснялки, музыкальные клипы и другое; они не переносимые.
What are similar projects?infinite-livestream, LTX-Video, CodeVideoModel, awesome-minimax-h3-integration, hyperflow, DreamX-Creator, CogVideo, FreeVideo
Which topics is it in?minimax-h3, minimax, open-weights, vlm, image-to-video, audio-generation, text-to-video, multimodal, video-generation, transformer, multilingual, prompt-engineering
Creator
MiniMax-AI
Size
91 MB
Stars
10.1K
Updated
CommitAug 15
Age
2mo
Commits · 90 Days