MiniMax H3 部署全指南：API 调用、本地 SGLang 部署与 Full 2K Workflow

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。

通过聚合平台接入（统一 Key 管理）

如果你的项目同时调用 MiniMax H3 和其他模型（DeepSeek、Kimi、GLM 等），也可以通过七牛云 AI Token Plan 接入——MiniMax 在其支持的模型列表内，base_url 换成七牛云端点，其余代码结构不变：

# 通过七牛云接入 MiniMax H3（兼容 OpenAI 协议，统一 API Key）
BASE_URL = "https://api.qnaigc.com/v1"   # 七牛云端点
 
# 视频生成请求结构与官方 API 相同，model 字段填 MiniMax-H3

多模型并用时，统一 Key 省去为每个模型维护独立鉴权配置的麻烦；对只调 MiniMax 单一模型的项目，直连官方 API 更直接。详见七牛云 AI Token Plan（qiniu.com/ai/plan）。

路径二：本地部署 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

● 七牛云 MiniMax Token Plan：qiniu.com/ai/plan