MiniMax H3，2026年8月开源的全模态视频生成系统，由三个模块串联构成：H3-Context-IR（多模态指令理解，托管API）、H3-Base（33B核心生成，已开源，输出768p）、H3-Regenerate-2K（超分还原2K，托管API，尚未开源）。H3-Base提供FL2VA（首尾帧）和Ref2VA（全能参考）两个开源检查点，可通过SGLang、vLLM或diffusers本地部署；完整的2K输出需要将本地H3-Base与官方Context-IR和Regenerate-2K API组合为Full 2K Workflow。本文从零梳理三条路径的完整配置：直接调用官方API（H3-2K直出）、本地部署H3-Base输出768p、Full 2K三段式流水线，附完整代码示例和关键参数说明，帮助开发者选择适合自身场景的接入方式。

三模块架构与开源边界

动手之前，先弄清楚哪部分可以本地跑，哪部分必须调API，免得走弯路：

官方建议：即使本地部署了H3-Base，也应先通过H3-Context-IR API处理输入，再把增强后的提示词喂给本地模型——Context-IR对最终生成质量影响显著，绕过它直接输入原始Prompt效果会下降。

两个开源检查点对应不同输入场景：

路径一：官方API直接调用（H3-2K直出，最省事）

适合：不需要本地部署、数据非敏感、想最快出2K视频。

获取API Key

前往platform.minimaxi.com（国内）或platform.minimax.io（海外）注册账号，在「账户管理 → 接口密钥」中生成API Key。

最简文生视频

import os
import time
import requests

api_key = os.environ["MINIMAX_API_KEY"]
headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}
BASE_URL = "https://api.minimaxi.com"   # 国内端点；海外改为 api.minimax.io

# 第一步：提交任务
def create_t2va_task(prompt: str, duration: int = 5, ratio: str = "16:9") -> str:
    url = f"{BASE_URL}/v2/video_generation"
    payload = {
        "model": "MiniMax-H3",
        "content": [{"type": "text", "text": prompt}],
        "resolution": "2K",
        "duration": duration,
        "ratio": ratio        # 文生视频必填，不能用adaptive
    }
    r = requests.post(url, headers=headers, json=payload)
    r.raise_for_status()
    return r.json()["task_id"]

# 第二步：轮询任务状态
def poll_task(task_id: str) -> dict:
    url = f"{BASE_URL}/v2/query/video_generation"
    while True:
        r = requests.get(url, headers=headers, params={"task_id": task_id})
        r.raise_for_status()
        task = r.json()["task"]
        status = task["status"]
        if status == "succeeded":
            return task
        elif status in ("failed", "cancelled"):
            raise RuntimeError(f"任务失败：{task}")
        print(f"状态：{status}，等待中...")
        time.sleep(5)

# 第三步：下载视频
def download_video(task: dict, output_path: str):
    video_url = task["content"]["url"]
    r = requests.get(video_url, stream=True)
    r.raise_for_status()
    with open(output_path, "wb") as f:
        for chunk in r.iter_content(chunk_size=8192):
            f.write(chunk)
    print(f"已保存：{output_path}")

# 完整调用示例
task_id = create_t2va_task("镜头拍摄一个女性坐在咖啡馆里，她抬头看向窗外，镜头缓缓推向窗外的街道，暖色调。")
task = poll_task(task_id)
download_video(task, "output.mp4")

图生视频（首尾帧模式）

def create_fl2va_task(prompt: str, first_frame_url: str, duration: int = 8) -> str:
    url = f"{BASE_URL}/v2/video_generation"
    payload = {
        "model": "MiniMax-H3",
        "content": [
            {"type": "text", "text": prompt},
            {
                "type": "image_url",
                "image_url": {"url": first_frame_url},
                "role": "first_frame"    # 或last_frame / 同时传两张
            }
        ],
        "resolution": "2K",
        "duration": duration,
        "ratio": "adaptive"   # 图生视频由输入图片决定宽高比
    }
    r = requests.post(url, headers=headers, json=payload)
    r.raise_for_status()
    return r.json()["task_id"]

关键参数速查

请求体总大小上限64 MB，大文件建议通过公网URL传入，不推荐Base64。

路径二：本地部署H3-Base（输出768p）

适合：数据不出内网、需要微调、有GPU算力。

硬件要求

别看H3-Base是BF16精度的Omni Transformer权重，但推理时AdaLN相关的约13B参数可以预计算缓存，不常驻显存。推荐配置：

操作系统：Linux（CUDA）

下载权重

# 安装huggingface_hub CLI
pip install huggingface_hub

# 仅下载FL2VA检查点（文生视频 / 首尾帧）
hf download MiniMaxAI/MiniMax-H3 
  --include "model_index.json" "modular_model_index.json" "FL2VA/*" 
  --local-dir MiniMax-H3

# 同时下载两个检查点
hf download MiniMaxAI/MiniMax-H3 
  --include "model_index.json" "modular_model_index.json" "FL2VA/*" "Ref2VA/*" 
  --local-dir MiniMax-H3

国内网络可改用魔搭社区镜像：modelscope.cn/models/MiniMax/MiniMax-H3，通过ModelScope SDK或直接git clone下载。

每个检查点目录结构：

FL2VA/
├── model_index.json
├── processor/
├── tokenizer/
├── text_encoder/       # H3-Encoder（基于Qwen3-VL-32B第50层隐状态）
├── transformer/        # H3-Omni-Transformer主体
├── visual_vae/         # 空间16×、时间4×压缩的视频VAE
└── audio_vae/          # 32kHz立体声音频VAE

SGLang部署

pip install sglang

# 部署FL2VA（文生视频 / 首尾帧）
sglang serve 
  --model-path 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 MiniMax-H3 
  --num-gpus 4 
  --ulysses-degree 4 
  --performance-mode speed 
  --host 0.0.0.0 
  --port 30011 
  --model-variant ref2va

调用本地SGLang服务（768p推理）

import requests, base64, time

SGLANG_URL = "http://localhost:30010"

def local_generate(prompt: str, duration: int = 5, ratio: str = "16:9") -> str:
    payload = {
        "model": "MiniMax-H3",
        "content": [{"type": "text", "text": prompt}],
        "resolution": "768P",
        "duration": duration,
        "ratio": ratio
    }
    r = requests.post(f"{SGLANG_URL}/v2/video_generation", json=payload)
    r.raise_for_status()
    task_id = r.json()["task_id"]

    # 轮询本地任务
    while True:
        r = requests.get(f"{SGLANG_URL}/v2/query/video_generation",
                         params={"task_id": task_id})
        task = r.json()["task"]
        if task["status"] == "succeeded":
            # 本地输出通常为base64 Data URL或本地路径
            return task["content"]["url"]
        time.sleep(3)

vLLM部署（可选替代）

pip install vllm --torch-backend=auto

vllm serve MiniMax-H3/FL2VA 
  --trust-remote-code 
  --tensor-parallel-size 4

diffusers部署（适合研究 / 微调）

from diffusers import MiniMaxH3ModularPipeline

pipe = MiniMaxH3ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3")
# diffusers会自动按需拉取所需组件

路径三：Full 2K Workflow（本地H3-Base + 官方API串联）

这是MiniMax官方推荐的“复现最优质量”路径：

用户输入 → H3-Context-IR API → 结构化提示词
                                     ↓
                            本地SGLang (H3-Base)
                                     ↓
                              768p视频文件
                                     ↓
                         H3-Regenerate-2K API → 2K成片

环境变量配置

SGLANG_DEPLOYMENT_URL="http://localhost:30010"
MINIMAX_API_BASE="https://api.minimaxi.com"   # 国内
TOKEN="<你的MiniMax API Key>"

第一步：H3-Context-IR（增强提示词）

import os, time, requests

api_key = os.environ["MINIMAX_API_KEY"]
headers = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}

def run_context_ir(prompt: str, duration: int, ratio: str) -> str:
    """调用H3-Context-IR，返回结构化提示词字符串。"""
    payload = {
        "model": "MiniMax-H3",
        "content": [{"type": "text", "text": prompt}],
        "duration": duration,
        "ratio": ratio
    }
    r = requests.post(
        f"{os.environ['MINIMAX_API_BASE']}/v2/h3_context_ir",
        headers=headers, json=payload
    )
    r.raise_for_status()
    task_id = r.json()["task_id"]

    # 轮询直到完成
    while True:
        r = requests.get(
            f"{os.environ['MINIMAX_API_BASE']}/v2/query/video_generation",
            headers=headers, params={"task_id": task_id}
        )
        task = r.json()["task"]
        if task["status"] == "succeeded":
            # content.prompt是增强后的结构化提示词
            return task["content"]["prompt"]
        time.sleep(3)

Context-IR输出的content.prompt是一段详细的英文结构化描述，包含镜头描述（integrated_multimodal_description）、音景（overall_soundscape）、非剧情音乐（non_diegetic_music）三个字段。以10秒视频为例，典型输出约消耗8565 token（输入5650 + 输出2915）。

第二步：本地H3-Base生成768p

把Context-IR输出的结构化提示词直接传入本地SGLang服务：

def run_h3_base_local(enhanced_prompt: str, duration: int, ratio: str,
                      output_path: str = "h3_base_768p.mp4"):
    """用增强提示词调本地SGLang，保存768p视频。"""
    payload = {
        "model": "MiniMax-H3",
        "content": [{"type": "text", "text": enhanced_prompt}],
        "resolution": "768P",
        "duration": duration,
        "ratio": ratio
    }
    r = requests.post(
        f"{os.environ['SGLANG_DEPLOYMENT_URL']}/v2/video_generation",
        json=payload
    )
    r.raise_for_status()
    task_id = r.json()["task_id"]

    while True:
        r = requests.get(
            f"{os.environ['SGLANG_DEPLOYMENT_URL']}/v2/query/video_generation",
            params={"task_id": task_id}
        )
        task = r.json()["task"]
        if task["status"] == "succeeded":
            video_url = task["content"]["url"]
            # 下载保存到本地
            with open(output_path, "wb") as f:
                f.write(requests.get(video_url).content)
            return output_path
        time.sleep(3)

第三步：H3-Regenerate-2K（768p → 2K）

def run_regenerate_2k(original_prompt: str, video_path: str,
                      duration: int, ratio: str) -> str:
    """将本地768p视频超分到2K，返回最终视频URL。"""
    # 生产环境建议上传到公网URL；本地测试可用Base64 Data URL
    with open(video_path, "rb") as f:
        video_b64 = "data:video/mp4;base64," + __import__("base64").b64encode(f.read()).decode()

    payload = {
        "model": "MiniMax-H3",
        "content": [
            {"type": "text", "text": original_prompt},
            {
                "type": "video_url",
                "video_url": {"url": video_b64},
                "role": "base_video"
            }
        ],
        "resolution": "2K"
    }
    r = requests.post(
        f"{os.environ['MINIMAX_API_BASE']}/v2/video_regeneration",
        headers=headers, json=payload
    )
    r.raise_for_status()
    task_id = r.json()["task_id"]

    while True:
        r = requests.get(
            f"{os.environ['MINIMAX_API_BASE']}/v2/query/video_generation",
            headers=headers, params={"task_id": task_id}
        )
        task = r.json()["task"]
        if task["status"] == "succeeded":
            return task["content"]["url"]
        time.sleep(5)

# 完整Full 2K Workflow
def full_2k_workflow(user_prompt: str, duration: int = 10,
                     ratio: str = "16:9") -> str:
    print("Step 1: H3-Context-IR 增强提示词...")
    enhanced = run_context_ir(user_prompt, duration, ratio)

    print("Step 2: 本地H3-Base生成768p...")
    local_video = run_h3_base_local(enhanced, duration, ratio)

    print("Step 3: H3-Regenerate-2K超分到2K...")
    final_url = run_regenerate_2k(enhanced, local_video, duration, ratio)

    print(f"完成：{final_url}")
    return final_url

三条路径怎么选

常见问题

Q：H3-Context-IR不开源，可以自己替代吗？

官方提供了Prompting Guidance文档（HuggingFace README），说明了如何手工构建包含integrated_multimodal_description、overall_soundscape、non_diegetic_music三部分的结构化提示词，给有Prompt Engineering能力的团队提供替代路径。自建系统质量低于官方Context-IR，但在简单场景下差距可控。

Q：H3-Regenerate-2K API未开源，Full 2K Workflow是否完全本地化？

目前不能完全本地化——H3-Base 768p生成可以本地完成，但2K超分必须调官方API。MiniMax表示H3-Regenerate-2K后续会单独开源。如果无法接受任何外部API调用，当前只能输出768p。

Q：本地部署后如何计费？

本地部署H3-Base本身不产生API费用，仅服务器GPU成本。调用官方H3-Context-IR和H3-Regenerate-2K API按使用量计费（具体定价见platform.minimaxi.com/pricing）。直接调官方/v2/video_generation端点输出2K按0.8元/秒计费，一次性包含三个模块。

Q：多模态参考（Ref2VA）和首尾帧（FL2VA）如何搭配？

两种模式互斥，不能在同一请求中混用。first_frame / last_frame角色的图片属于FL2VA模式，reference_image / reference_video / reference_audio属于Ref2VA模式，混用会报参数错误。需要同时控制首帧和参考风格的场景，官方目前没有单次请求支持，可以分两步：先用Ref2VA生成带参考风格的视频，再用该视频的首帧做第二次FL2VA请求。

Q：本地部署时能否同时运行FL2VA和Ref2VA？

两个检查点可以在不同端口同时运行，但各自需要一套4卡配置（或合理分配GPU资源）。SGLang的--port参数隔离两个服务，代码里按任务类型路由到对应端口即可。

小结

MiniMax H3的三模块设计意味着开发者需要根据数据合规要求和成本预算在三条路径中做选择：直接调官方API最省事，0.8元/秒一步到位；本地部署H3-Base能把数据留在内网，但目前2K超分仍依赖官方API；Full 2K Workflow是质量最优的本地+云端混合方案，适合对画面要求高且有工程能力的团队。H3-Regenerate-2K开源后，完全本地化2K流水线将成为可能。

数据来源：MiniMax H3官方HuggingFace README（huggingface.co/MiniMaxAI/MiniMax-H3，2026年8月4日）、MiniMax开放平台API文档（platform.minimaxi.com/docs，2026年8月）、MiniMax H3发布公告（minimaxi.com/blog/minimax-h3，2026年7月31日）。

延伸阅读

• MiniMax H3开源权重与完整README：huggingface.co/MiniMaxAI/MiniMax-H3
• MiniMax开放平台API文档（国内）：platform.minimaxi.com/docs/guides/video-generation
• SGLang官方MiniMax-H3部署指南：docs.sglang.io/cookbook/diffusion/MiniMax/MiniMax-H3