MiniMax H3部署与API接入实战：768P本地推理到Full 2K

MiniMax H3部署与API接入实战：从768P本地推理到Full 2K工作流

截至2026年8月，AI视频生成模型正从单一的“文生视频”能力转向统一多模态理解、原生音视频联合生成和复杂参考素材控制。MiniMax H3便是在这一背景下推出的全模态视频生成系统。它于2026年7月31日正式发布，随后在8月初开放部分模型权重，支持文本、图片、视频与音频组成的多模态上下文，最长可生成15秒视频，并输出原生32kHz立体声音频。

与传统单模型架构不同，MiniMax H3并不是一个可以整体下载运行的单一检查点，而是由H3-Context-IR、H3-Base和H3-Regenerate-2K三个模块协同完成视频生成。其中只有H3-Base已经开放权重，其余两个模块目前仍以托管API形式提供。

因此，开发者在接入MiniMax H3时，通常需要在以下三条路线中做选择：

1. 直接调用官方MiniMax H3 API，输出768P或2K视频；
2. 本地部署H3-Base，生成768P音视频；
3. 将H3-Context-IR API、本地H3-Base与H3-Regenerate-2K API串联，构建Full 2K Workflow。

本文将从系统架构、API调用、本地部署、Full 2K工作流和多模型API中转站接入等角度，梳理MiniMax H3的完整技术路径。

一、MiniMax H3三模块架构与开源范围

MiniMax H3的完整生成链路可以理解为“输入理解—基础生成—高分辨率再生成”三个阶段。

模块	主要作用	当前开放状态	常见接入方式
H3-Context-IR	理解文本、图片、视频和音频之间的关系，将自由输入转换为结构化视频描述	未开源	托管API
H3-Base	根据结构化上下文联合生成视频画面与立体声音频	已开放权重	SGLang、vLLM、diffusers、ComfyUI
H3-Regenerate-2K	将768P基础结果与原始上下文再次输入模型，重新生成2K版本	暂未开源	托管API

H3-Context-IR并不只是普通的Prompt扩写工具。它需要分析参考图片对应哪个角色、参考视频需要复用动作还是镜头语言、音频是作为对白、环境音还是配乐使用，并在时间轴上组织不同信息。系统最终会输出H3-Base能够处理的Context Intermediate Representation。官方模型说明明确指出，这一模块会显著影响复杂多模态任务的最终质量。

H3-Base负责核心音视频生成，默认生成短边约768像素的视频。H3-Regenerate-2K则不是传统插值式超分，而是将基础视频与原始上下文重新送入生成系统，通过再生成方式恢复纹理、人物细节和场景信息。 需要注意的是，MiniMax H3目前只能做到“部分本地化”。开发者可以完全在本地运行H3-Base，但想复现官方2K输出流程，仍需调用H3-Context-IR和H3-Regenerate-2K。

二、FL2VA与Ref2VA两个开源检查点

H3-Base开放了两个任务检查点，分别面向首尾帧控制和多模态参考生成。

检查点	模式	支持的输入
H3-Base FL2VA	Text/First/Last Frame to Video-Audio	文本，可附首帧、尾帧或首尾两张图片
H3-Base Ref2VA	Reference to Video-Audio	文本、参考图片、参考视频、参考音频

FL2VA可以在不上传图片时执行文生视频，也可以通过一张图片指定首帧或尾帧，通过两张图片同时限定视频起点和终点。

Ref2VA面向更复杂的参考控制场景。当前模型规范支持最多9张参考图片、3段参考视频和3段参考音频。单段视频或音频时长为2至15秒，所有参考视频的总时长不超过15秒；音频不能作为唯一参考输入，必须搭配图片或视频使用。全部媒体文件数量合计最多12个。Hugging Face

首尾帧模式与多模态参考模式不能在同一请求中混合。例如，已经设置role=first_frame后，不能再加入role=reference_video。工程中需要在提交任务前判断输入类型，并把请求路由到FL2VA或Ref2VA对应的服务。

三、路径一：直接调用MiniMax H3官方API

对于不准备维护GPU服务器、需要快速完成原型验证或直接生成2K视频的团队，官方API是较容易落地的方案。

当前V2视频生成接口使用统一的content数组接收文本、图片、视频和音频，接口地址为：

POST /v2/video_generation

文生视频、首尾帧图生视频和多模态参考视频使用同一入口，通过type与role区分不同素材。官方API支持4至15秒时长、24FPS、768P与2K输出，并提供多种常用宽高比。

1. Python基础配置

import os
import time
from pathlib import Path

import requests

API_KEY = os.environ["MINIMAX_API_KEY"]
API_BASE = os.getenv(
    "MINIMAX_API_BASE",
    "https://api.minimaxi.com"
)

HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

TIMEOUT = 120

国内开发环境可以使用api.minimaxi.com，海外项目则应切换到对应的国际端点。API Key不应直接写入代码仓库，建议通过环境变量、密钥管理服务或容器Secret注入。

2. 创建文生视频任务

def create_video_task(
    prompt: str,
    duration: int = 5,
    ratio: str = "16:9",
    resolution: str = "2K",
) -> str:
    if not 4 <= duration <= 15:
        raise ValueError("duration必须在4至15秒之间")

    payload = {
        "model": "MiniMax-H3",
        "content": [
            {
                "type": "text",
                "text": prompt,
            }
        ],
        "resolution": resolution,
        "duration": duration,
        "ratio": ratio,
        "aigc_watermark": False,
    }

    response = requests.post(
        f"{API_BASE}/v2/video_generation",
        headers=HEADERS,
        json=payload,
        timeout=TIMEOUT,
    )
    response.raise_for_status()

    data = response.json()
    if "task_id" not in data:
        raise RuntimeError(f"未获取task_id：{data}")

    return data["task_id"]

文生视频场景必须明确指定宽高比，不能使用adaptive。常见取值包括16:9、9:16、1:1、4:3、3:4和21:9。

3. 查询异步任务

def query_task(task_id: str) -> dict:
    response = requests.get(
        f"{API_BASE}/v2/query/video_generation",
        headers=HEADERS,
        params={"task_id": task_id},
        timeout=TIMEOUT,
    )
    response.raise_for_status()
    return response.json()["task"]


def wait_for_task(
    task_id: str,
    interval: int = 5,
    max_wait: int = 1800,
) -> dict:
    started_at = time.time()

    while True:
        task = query_task(task_id)
        status = task.get("status")

        if status == "succeeded":
            return task

        if status in {"failed", "cancelled"}:
            raise RuntimeError(f"视频任务未完成：{task}")

        if time.time() - started_at > max_wait:
            raise TimeoutError(f"任务等待超时：{task_id}")

        print(f"当前状态：{status}")
        time.sleep(interval)

生产环境不一定要持续轮询。接口支持配置callback_url，任务状态变化后由服务端向业务系统推送通知。对于批量生成平台，回调模式通常比轮询更容易控制并发和请求数量。

4. 下载生成结果

def download_video(video_url: str, output_file: str) -> Path:
    output_path = Path(output_file)
    output_path.parent.mkdir(parents=True, exist_ok=True)

    with requests.get(
        video_url,
        stream=True,
        timeout=TIMEOUT,
    ) as response:
        response.raise_for_status()

        with output_path.open("wb") as file:
            for chunk in response.iter_content(1024 * 1024):
                if chunk:
                    file.write(chunk)

    return output_path

完整调用方式如下：

prompt = (
    "写实电影镜头。一名女性坐在靠窗的咖啡馆座位上，"
    "她缓慢抬头望向窗外，镜头从中景平稳推进，"
    "最后越过玻璃转向傍晚街道。暖色自然光，"
    "保留咖啡馆环境声与轻微城市背景声。"
)

task_id = create_video_task(
    prompt=prompt,
    duration=8,
    ratio="16:9",
    resolution="2K",
)

task = wait_for_task(task_id)
video_url = task["content"]["url"]

download_video(video_url, "outputs/h3_t2v_2k.mp4")

四、首帧、尾帧与多模态参考输入

1. 首帧图生视频

def create_first_frame_task(
    prompt: str,
    image_url: str,
    duration: int = 8,
) -> str:
    payload = {
        "model": "MiniMax-H3",
        "content": [
            {
                "type": "text",
                "text": prompt,
            },
            {
                "type": "image_url",
                "image_url": {
                    "url": image_url,
                },
                "role": "first_frame",
            },
        ],
        "resolution": "2K",
        "duration": duration,
        "ratio": "adaptive",
    }

    response = requests.post(
        f"{API_BASE}/v2/video_generation",
        headers=HEADERS,
        json=payload,
        timeout=TIMEOUT,
    )
    response.raise_for_status()
    return response.json()["task_id"]

尾帧控制只需要将role改为last_frame。同时控制首帧和尾帧时，在content中放入两张图片，并分别设置对应角色。

2. 多模态参考生成

def create_reference_task(
    prompt: str,
    reference_image: str,
    reference_video: str,
    reference_audio: str,
    duration: int = 10,
) -> str:
    payload = {
        "model": "MiniMax-H3",
        "content": [
            {
                "type": "text",
                "text": prompt,
            },
            {
                "type": "image_url",
                "image_url": {
                    "url": reference_image,
                },
                "role": "reference_image",
            },
            {
                "type": "video_url",
                "video_url": {
                    "url": reference_video,
                },
                "role": "reference_video",
            },
            {
                "type": "audio_url",
                "audio_url": {
                    "url": reference_audio,
                },
                "role": "reference_audio",
            },
        ],
        "resolution": "768P",
        "duration": duration,
        "ratio": "16:9",
    }

    response = requests.post(
        f"{API_BASE}/v2/video_generation",
        headers=HEADERS,
        json=payload,
        timeout=TIMEOUT,
    )
    response.raise_for_status()
    return response.json()["task_id"]

请求体总大小上限为64MB。较大的视频和音频素材应先上传至对象存储或CDN，再以公网URL提交。Base64更适合短期测试，不适合生产环境的大文件传输。

五、路径二：本地部署H3-Base生成768P视频

本地部署适合对数据边界有明确要求、需要在内网运行或准备研究模型结构的团队。H3-Base的两个检查点采用BF16精度，包含处理器、Tokenizer、文本编码器、Omni Transformer、Visual VAE和Audio VAE等组件。

H3-Omni-Transformer是一个约33B参数的稠密单流Transformer，其中约13B参数位于AdaLN相关分支。由于部分调制结果可以预计算和缓存，纯推理部署不一定需要让所有相关参数持续占用显存。实际资源需求仍会受到视频长度、分辨率、并行策略、框架版本和注意力实现影响。

1. 下载FL2VA权重

pip install -U huggingface_hub

hf download MiniMaxAI/MiniMax-H3 \
  --include "model_index.json" \
            "modular_model_index.json" \
            "FL2VA/*" \
  --local-dir MiniMax-H3

同时部署FL2VA与Ref2VA时，可以一次下载两个目录：

hf download MiniMaxAI/MiniMax-H3 \
  --include "model_index.json" \
            "modular_model_index.json" \
            "FL2VA/*" \
            "Ref2VA/*" \
  --local-dir MiniMax-H3

每个任务目录大致包含以下组件：

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

2. 使用SGLang启动FL2VA

官方示例采用4卡并行运行：

pip install -U sglang

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版本对模型路径、任务接口和性能参数的实现可能变化，正式部署前应锁定Python、PyTorch、CUDA、SGLang和模型仓库版本。

3. 使用diffusers加载

H3仓库同时提供适用于diffusers的组件索引。研究型环境可以通过模块化Pipeline按需拉取组件：

import torch
from diffusers import ModularPipeline

pipeline = ModularPipeline.from_pretrained(
    "MiniMaxAI/MiniMax-H3",
    torch_dtype=torch.bfloat16,
)

具体Pipeline类名和推理参数应以当前diffusers版本中的H3示例为准，不建议把开发版API直接固化进长期生产代码。

4. vLLM与ComfyUI

H3-Base也列出了vLLM和ComfyUI接入路径。vLLM更适合统一服务化部署，ComfyUI则适合以节点形式组合T2V、FL2VA和Ref2VA工作流。由于视频模型需要处理较长的时空序列，本地部署时应重点关注显存峰值、任务排队、临时文件清理和GPU故障恢复，而不只是模型能否成功启动。

六、路径三：搭建Full 2K Workflow

Full 2K Workflow将官方托管模块与本地H3-Base组合起来：

用户原始输入
    ↓
H3-Context-IR API
    ↓
结构化增强提示词
    ↓
本地H3-Base
    ↓
768P音视频
    ↓
H3-Regenerate-2K API
    ↓
2K最终视频

这一方案的主要价值在于，核心生成阶段可以留在自建环境中，同时使用官方上下文理解与2K再生成能力。它并不是完全离线方案，因为第一阶段和第三阶段仍会向外部API传输必要数据。

1. 调用H3-Context-IR

def create_context_ir_task(
    content: list[dict],
    duration: int,
    ratio: str,
) -> str:
    payload = {
        "model": "MiniMax-H3",
        "content": content,
        "duration": duration,
        "ratio": ratio,
    }

    response = requests.post(
        f"{API_BASE}/v2/h3_context_ir",
        headers=HEADERS,
        json=payload,
        timeout=TIMEOUT,
    )
    response.raise_for_status()
    return response.json()["task_id"]


def get_enhanced_prompt(
    content: list[dict],
    duration: int,
    ratio: str,
) -> str:
    task_id = create_context_ir_task(
        content=content,
        duration=duration,
        ratio=ratio,
    )
    task = wait_for_task(task_id)
    return task["content"]["prompt"]

Context-IR输出通常会包含三个主要部分：

integrated_multimodal_description
overall_soundscape
non_diegetic_music

其中第一部分描述镜头、角色、动作、时间节点和参考素材关系；第二部分组织环境声、对白和画内声音；第三部分描述非剧情音乐。官方公开案例中，一个10秒文本任务的Context-IR输入与输出合计超过8000 Token，说明该阶段并非简单的几句Prompt扩展。

2. 本地生成768P基础视频

def generate_local_base_video(
    enhanced_prompt: str,
    duration: int,
    ratio: str,
    output_path: str,
) -> str:
    local_base = os.environ["SGLANG_DEPLOYMENT_URL"]

    payload = {
        "model": "MiniMax-H3",
        "content": [
            {
                "type": "text",
                "text": enhanced_prompt,
            }
        ],
        "resolution": "768P",
        "duration": duration,
        "ratio": ratio,
    }

    response = requests.post(
        f"{local_base}/v2/video_generation",
        json=payload,
        timeout=TIMEOUT,
    )
    response.raise_for_status()

    task_id = response.json()["task_id"]

    while True:
        result = requests.get(
            f"{local_base}/v2/query/video_generation",
            params={"task_id": task_id},
            timeout=TIMEOUT,
        )
        result.raise_for_status()

        task = result.json()["task"]
        status = task["status"]

        if status == "succeeded":
            video_url = task["content"]["url"]
            download_video(video_url, output_path)
            return output_path

        if status in {"failed", "cancelled"}:
            raise RuntimeError(task)

        time.sleep(3)

本地SGLang实际暴露的路由和返回结构可能随版本变化。接入时应先用官方仓库提供的T2VA、FL2VA或Ref2VA示例验证，再将调用封装到业务代码中。

3. 将本地视频提交给H3-Regenerate-2K

生产环境建议先把本地768P视频上传至可访问的对象存储，再把URL作为base_video传入。

def create_regeneration_task(
    original_content: list[dict],
    base_video_url: str,
) -> str:
    content = list(original_content)

    content.append({
        "type": "video_url",
        "video_url": {
            "url": base_video_url,
        },
        "role": "base_video",
    })

    payload = {
        "model": "MiniMax-H3",
        "content": content,
        "resolution": "2K",
    }

    response = requests.post(
        f"{API_BASE}/v2/video_regeneration",
        headers=HEADERS,
        json=payload,
        timeout=TIMEOUT,
    )
    response.raise_for_status()

    return response.json()["task_id"]

视频再生成接口不是通用视频超分工具，只接受符合H3-Base 768P输出规范的源视频。提交时需要保留生成基础视频时所对应的原始上下文，并额外加入一个role=base_video的视频项。

完整工作流可以封装为：

def full_2k_workflow(
    user_prompt: str,
    duration: int = 10,
    ratio: str = "16:9",
) -> str:
    original_content = [
        {
            "type": "text",
            "text": user_prompt,
        }
    ]

    print("阶段一：生成Context IR")
    enhanced_prompt = get_enhanced_prompt(
        content=original_content,
        duration=duration,
        ratio=ratio,
    )

    print("阶段二：本地生成768P")
    local_file = generate_local_base_video(
        enhanced_prompt=enhanced_prompt,
        duration=duration,
        ratio=ratio,
        output_path="outputs/h3_base_768p.mp4",
    )

    print("阶段三：上传基础视频")
    base_video_url = upload_to_object_storage(local_file)

    print("阶段四：再生成2K")
    task_id = create_regeneration_task(
        original_content=original_content,
        base_video_url=base_video_url,
    )

    task = wait_for_task(task_id)
    return task["content"]["url"]

其中upload_to_object_storage需要根据项目使用的S3、OSS、COS或其他对象存储自行实现。

七、MiniMax H3三种接入方式如何选择

使用场景	建议路线	主要特点
快速验证、调用量有限	官方API直出	无需维护GPU，工程链路较短
数据需要留在内网	本地H3-Base	核心生成在本地完成，当前输出以768P为主
需要2K且希望自建核心生成服务	Full 2K Workflow	本地与托管API结合，部署复杂度较高
需要可视化调试	ComfyUI工作流	便于调整参考素材与节点参数
同时调用多个视频和语言模型	大模型API中转站	统一鉴权、模型路由和任务管理

直接API调用适合先跑通业务流程。本地部署的前期成本较高，但在有稳定任务量、GPU资源和运维能力时，更容易控制数据位置与生成队列。Full 2K Workflow则需要同时维护GPU服务、素材存储、异步任务、外部API和失败重试机制，适合已经具备完整工程团队的项目。

八、通过大模型API中转站接入Seedance 2.5

除了MiniMax H3，2026年下半年视频生成模型的另一个重要方向是Seedance 2.5。该模型面向最长30秒的连续叙事视频，强化了参考控制、视频编辑、镜头运动与复杂制作流程。

当一个项目同时使用MiniMax H3、Seedance 2.5、语言模型、图像生成模型和语音模型时，逐一维护不同厂商的Key、Endpoint、鉴权方法和任务状态结构会增加工程复杂度。此时可以考虑星链4SAPI这类大模型API中转站，通过统一账户管理多种模型调用。

需要说明的是，大模型API中转站并不会改变底层模型的生成能力，其主要作用位于接入层：

1. 统一管理API Key和请求端点；
2. 对不同模型名称进行路由；
3. 集中记录调用日志、消耗和错误信息；
4. 减少业务代码中重复的鉴权配置；
5. 为模型切换、备用路由和多供应商调用提供统一封装。

在确认平台控制台已经开放Seedance 2.5后，调用结构通常可以封装为异步视频任务。实际base_url、模型标识符、请求字段和查询接口必须以平台当前文档为准，不应直接照搬其他服务商的参数。

import os
import requests

GATEWAY_API_KEY = os.environ["GATEWAY_API_KEY"]
GATEWAY_BASE_URL = os.environ["GATEWAY_BASE_URL"]

headers = {
    "Authorization": f"Bearer {GATEWAY_API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "model": "seedance-2.5",
    "prompt": (
        "一段连续的城市夜景叙事。人物从地铁站走出，"
        "穿过雨后的街道，镜头保持人物身份与服装一致，"
        "最后停在霓虹灯下。包含自然环境声。"
    ),
    "duration": 30,
    "ratio": "16:9",
}

response = requests.post(
    f"{GATEWAY_BASE_URL}/video/generations",
    headers=headers,
    json=payload,
    timeout=120,
)

response.raise_for_status()
print(response.json())

以星链API这类大模型API中转站接入Seedance 2.5时，应优先检查四项内容：平台展示的准确模型ID、是否支持参考图片或参考视频、异步任务查询方式、生成结果的保存期限。公开视频模型仍处于快速更新阶段，同一模型在不同平台的参数开放范围可能并不完全一致。星链API公开内容目前已覆盖Seedance 2.5接入与模型能力说明，但生产项目仍应以控制台实时模型列表和接口文档为准。

九、部署过程中容易忽略的问题

1. 不要把H3-Regenerate-2K当作普通超分接口

它需要H3生成的768P基础结果和对应上下文，不能任意上传一段普通视频后直接转换为2K。

2. Context-IR可能接触原始素材

即使H3-Base运行在内网，只要使用官方Context-IR，文本、图片、视频或音频仍可能被提交至托管服务。严格数据隔离场景应自行构建上下文处理层，并接受生成质量可能发生变化。

3. 首尾帧和全能参考不能混用

first_frame、last_frame属于FL2VA；reference_image、reference_video和reference_audio属于Ref2VA。两类角色同时出现会触发参数校验错误。

4. 双检查点同时部署会增加资源压力

FL2VA和Ref2VA可以分别部署在不同端口，但它们是两套检查点。是否能够共享部分GPU资源，需要根据显存容量、并发量和框架调度能力测试，不能只通过修改端口实现零成本并行。

5. 固定依赖版本

视频生成框架更新速度较快。建议在验证通过后固定模型提交版本、CUDA、PyTorch、SGLang、vLLM和diffusers版本，并保存可复现的容器镜像。

十、总结

MiniMax H3的开放方式并不是把完整2K系统一次性交给开发者，而是开放承担核心生成工作的H3-Base，同时保留H3-Context-IR与H3-Regenerate-2K托管服务。

需要快速完成MiniMax H3 API接入的项目，可以直接使用V2视频生成接口；需要数据留在本地的团队，可以通过SGLang、vLLM、diffusers或ComfyUI运行H3-Base，输出768P音视频；需要接近官方2K流程的开发者，则可以搭建Full 2K Workflow，将托管上下文处理、本地基础生成和托管2K再生成串联起来。

对于同时调用MiniMax H3、Seedance 2.5以及其他语言、图像和语音模型的系统，星链API这类大模型API中转站可以作为统一接入层使用，但仍需按照平台实时文档确认模型名称、输入限制和异步任务格式。

随着后续稀疏注意力实现、推理框架适配和H3-Regenerate-2K模块逐步完善，MiniMax H3的本地部署成本与工程复杂度仍可能继续变化。现阶段更稳妥的方式，是先根据数据合规、输出分辨率、生成规模和GPU资源选择接入路线，再决定是否建设完整的本地音视频生成基础设施。