# MiniMax-H3

  
    
  

MiniMax-H3 同时生成视频及其配套音轨。单个 transformer 对一条打包序列进行去噪，该序列包含文本条件、条件媒体以及目标视频和音频潜变量。系统不包含独立的声码器，也没有事后的音频处理步骤：视频和音频均出自同一个去噪循环。

您可以在 [MiniMaxAI](https://huggingface.co/MiniMaxAI) 组织下找到原始的 MiniMax-H3 检查点。

MiniMax-H3 仅以 [Modular Diffusers](../../modular_diffusers/overview) 块的形式集成，方式与 [Anima](./anima) 相同：这些块及其 [MiniMaxH3ModularPipeline](/docs/diffusers/v0.43.0/zh/api/pipelines/minimax_h3#diffusers.MiniMaxH3ModularPipeline) 构成了完整的集成，不存在 `DiffusionPipeline` 部分。

## 检查点布局

MiniMax-H3 以两个检查点分区发布，除 transformer 外，所有组件均相同，因此 diffusers 转换将两者放入**同一个仓库**中：

| 子文件夹 | 工作流程 |
|---|---|
| `transformer/` | `t2va`（仅文本），`fl2va`（首帧和/或末帧） |
| `transformer_ref/` | `ref2va`（图像、视频和音频参考的有序混合） |

除 Transformer 之外的所有组件，即视频 VAE、音频 VAE、Qwen3-VL 条件器、其分词器和处理器，以及两个调度器，均为共享组件，仅存储一次。

条件器是一个 `Qwen3VLForConditionalGeneration`，MiniMax-H3 读取的是其第 50 个解码器层之后的 *未归一化* 隐藏状态，而非最后一层，因此完整的发布检查点被使用，但其语言模型头未被使用。

这三个任务都是 [MiniMaxH3Blocks](/docs/diffusers/v0.43.0/zh/api/pipelines/minimax_h3#diffusers.MiniMaxH3Blocks) 的工作流，该仓库包含一个 `modular_model_index.json`，其中为每个组件指定了各自的加载规范。若要提供单一任务的服务，请将工作流传递给 `from_pretrained`：它仅保留该工作流的块，因此管线的签名（`pipe.doc`）会准确记录该任务的输入，仅声明该任务的组件，并且 `load_components` 会精确获取它们对应的子文件夹——`t2va` / `fl2va` 管线绝不会触及 `transformer_ref/`，而 `ref2va` 管线绝不会触及 `transformer/`。

```py
import torch
from diffusers import ModularPipeline

pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3", workflow="ref2va")
pipe.load_components(dtype=torch.bfloat16)
```

> [!TIP]
> `pipe.doc` 会打印出当前流水线所接收和返回的内容——包括每个输入及其默认值、预期的组件以及产生的输出。经过裁剪后，它只描述单一工作流，从而精确地说明该任务，这是在发起请求之前快速了解请求所需内容的最快方式。

若要使所有工作流都可在同一条流水线中使用，请省略 `workflow` 参数：此时流水线会根据每次调用时传入的输入，自动选择相应的工作流。

```py
pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3")
```

*加载*仍然可以按一次一个工作流进行。这一次调用会获取 `transformer/` 以及所有共享组件，同时服务于 `t2va` 和 `fl2va`：

```py
pipe.load_components(workflow="t2va", dtype=torch.bfloat16)
```

不带 `workflow=` 的普通 `load_components()` 会加载 **两个** 61.7GB 的 transformer 分区，这使得一个 pipeline 无需再次调用加载即可服务于全部三个工作流。将其与 [ComponentsManager](/docs/diffusers/v0.43.0/zh/api/modular_diffusers/pipeline_components#diffusers.ComponentsManager) 和自动 offloading 配合使用：权重驻留在主机内存中，管理器仅将每个步骤所需的权重移至加速器，因此当 `ref2va` 去噪器需要设备时，策略会 offload 出足够空间的内容。请参阅 [Memory](#memory) 了解相关配方。

## 两种调度器

在每一步中，视频和音频潜变量在单次 transformer 调用内分别遵循两个不同的调度方案，因此这些块需要两个 [MiniMaxH3Scheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/minimax_h3#diffusers.MiniMaxH3Scheduler) 实例：`scheduler` 用于视频潜变量（在发布的检查点中 `shift=12.0`），`audio_scheduler` 用于音频潜变量（`shift=3.0`）。

两个 transformer 分区均经过 guidance 蒸馏，因此这一点适用于所有工作流：guidance 已融入权重中，不存在 guider，也没有 `negative_prompt` 和 `guidance_scale`，且每一步仅执行一次前向传播。

## 生成约束

- **24 fps，时长 5 到 15 秒。** `num_frames` 会被向上取整到视频 VAE 可解码的下一个 `17 * n + 5`，且生成的时长必须落在该区间内。
- **短边为 768 像素。** `height` 和 `width` 默认采用 MiniMax-H3 自身的画布尺寸，以匹配首帧关键帧的宽高比（若无关键帧则为 16:9），且必须是 32 的倍数。
- **一个生成器，三次采样。**请求首先从传入的 `generator` 中采样关键帧或参考条件噪声，然后采样视频噪声，最后采样音频噪声。因此，从相同的生成器状态运行两次会返回相同的视频和音轨。传入 `latents` 或 `audio_latents` 会替换对应的采样。
- **`num_inference_steps` 统计 sigma 网格点**（包含末尾的 `0`），因此它会使模型评估次数少一次。

## 内存

仅 Transformer 在 bfloat16 下就占用 61.7 GB，而 Qwen3-VL 条件器又额外占用 62.1 GB，因此加载方案取决于硬件配置。在所有配置中，较小的画布尺寸是提升速度的最大杠杆：`height` 和 `width` 只需是 32 的倍数即可，960x544 的分辨率每步运行速度比训练时的 1344x768 快约 2.3 倍。

在一张 80 GB 的显卡上，将组件注册到 [ComponentsManager](/docs/diffusers/v0.43.0/zh/api/modular_diffusers/pipeline_components#diffusers.ComponentsManager) 中，并让它负责将组件在加速器上移动和移出：

```py
import torch
from diffusers import ComponentsManager, ModularPipeline

manager = ComponentsManager()
pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3", components_manager=manager)
pipe.load_components(workflow="t2va", dtype=torch.bfloat16)
manager.enable_auto_cpu_offload(device="cuda", memory_reserve_margin="12GB")  # or "mps", "xpu", "cpu"
pipe.transformer.set_attention_backend("_flash_3_hub")  # Hopper, roughly 3x faster; kernels fetched from the Hub
```

在消费级显卡（24 至 32 GB）上，在加载时将两个大型组件量化为 int8，并从 CPU 内存中流式传输 Transformer 的块。以下所有内容仅使用受支持的加载器，无需任何补丁，并且可以直接从 bfloat16 检查点运行：

```py
import torch
from diffusers import MiniMaxH3Transformer3DModel, ModularPipeline, TorchAoConfig
from diffusers.hooks import apply_group_offloading
from transformers import Qwen3VLForConditionalGeneration
from transformers import TorchAoConfig as TransformersTorchAoConfig
from torchao.quantization import Int8WeightOnlyConfig

pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3")
pipe.update_components(
    transformer=MiniMaxH3Transformer3DModel.from_pretrained(
        "MiniMaxAI/MiniMax-H3", subfolder="transformer", dtype=torch.bfloat16,
        quantization_config=TorchAoConfig(
            Int8WeightOnlyConfig(version=2),
            modules_to_not_convert=[
                "proj_in", "audio_proj_in", "context_embedder", "time_embedder", "time_proj",
                "token_refiner", "norm_out", "proj_out", "audio_proj_out",
            ],
        ),
        low_cpu_mem_usage=False,
    ),
    text_encoder=Qwen3VLForConditionalGeneration.from_pretrained(
        "MiniMaxAI/MiniMax-H3", subfolder="text_encoder", dtype=torch.bfloat16,
        quantization_config=TransformersTorchAoConfig(
            Int8WeightOnlyConfig(version=2),
            modules_to_not_convert=["model.visual", "model.language_model.embed_tokens", "model.language_model.norm", "lm_head"],
        ),
    ),
)
pipe.load_components(workflow="t2va", dtype=torch.bfloat16)

# version=2 int8 tensors are pinnable, which streamed offload needs, and freezing removes the one autograd
# path the quantized tensors cannot serve.
pipe.transformer.requires_grad_(False)
pipe.text_encoder.requires_grad_(False)

offload = dict(onload_device=torch.device("cuda"), offload_device=torch.device("cpu"), use_stream=True)
pipe.transformer.enable_group_offload(offload_type="block_level", num_blocks_per_group=1, **offload)
apply_group_offloading(pipe.text_encoder.model, offload_type="leaf_level", **offload)
pipe.vae.to("cuda")  # or "mps", "xpu", "cpu"
pipe.audio_vae.to("cuda")
```

在 12 到 16 GB 显存下，同样的方案也可以将视频 VAE 组卸载（`offload_type="leaf_level"`，无流式处理），并使用较小的画布，例如 960x544。请注意权重将驻留在主机内存中：在 int8 精度下大约需要 75 GB。

使用两张显卡时，无需进行任何卸载操作：将流水线一分为二，并将每一半分别放置在各自的设备上。

```py
import torch
from diffusers import ComponentsManager, ModularPipeline

workflow = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3").blocks.get_workflow("t2va")

text_manager = ComponentsManager()
text_manager.enable_auto_cpu_offload(device="cuda:1")
conditioner = workflow.sub_blocks.pop("text_encoder").init_pipeline(
    "MiniMaxAI/MiniMax-H3", components_manager=text_manager
)
conditioner.load_components(dtype=torch.bfloat16)

manager = ComponentsManager()
manager.enable_auto_cpu_offload(device="cuda:0")
rest = workflow.init_pipeline("MiniMaxAI/MiniMax-H3", components_manager=manager)
rest.load_components(dtype=torch.bfloat16)

prompt = "A red fox trotting through a snowy pine forest, snow crunching underfoot"
state = conditioner(prompt=prompt)
results = rest(
    state=state,
    num_frames=124,
    generator=torch.Generator().manual_seed(42),
    output=["videos", "audio", "sampling_rate"],
)
```

两张 80 GB 显卡可以以这种方式运行完整的 bfloat16：每一半都能独立容纳在一张显卡上，因此一旦加载到显存中，就不会被换出到主机内存。两张 48 GB 显卡则可以在两个组件上都使用上述的 int8 加载方式，达到同样的效果。

## 文本和关键帧

[MiniMaxH3Blocks](/docs/diffusers/v0.43.0/zh/api/pipelines/minimax_h3#diffusers.MiniMaxH3Blocks) 支持文本生成视频与音频，以及关键帧条件控制。关键帧可以是视频的起始帧（`image`）、结束帧（`last_image`），或两者兼有。

```py
import torch
from diffusers import ComponentsManager, ModularPipeline
from diffusers.utils import load_image
from diffusers.utils.export_utils import encode_video

# 61.7GB of transformer and 62.1GB of conditioner do not sit on one accelerator, so the components are
# registered in a manager that moves each one on and off as the blocks reach it. See [Memory](#memory).
manager = ComponentsManager()
manager.enable_auto_cpu_offload(device="cuda")  # or "mps", "xpu", "cpu"

pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3", components_manager=manager)
pipe.load_components(workflow="fl2va", dtype=torch.bfloat16)

prompt = "A red fox trotting through a snowy pine forest, snow crunching underfoot"
# `output=` returns exactly the named outputs instead of the whole pipeline state.
outputs = ["videos", "audio", "sampling_rate"]

# Text to video + audio.
results = pipe(prompt=prompt, num_frames=124, generator=torch.Generator().manual_seed(42), output=outputs)

# First frame (and optionally last frame) to video + audio. The canvas follows the first keyframe.
image = load_image(
    "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/astronaut.jpg"
)
results = pipe(prompt=prompt, image=image, num_frames=124, generator=torch.Generator().manual_seed(42), output=outputs)

encode_video(
    results["videos"][0],
    fps=24,
    output_path="minimax_h3_fl2va.mp4",
    audio=results["audio"][0],
    audio_sample_rate=results["sampling_rate"],
)
```

视频和音频是联合生成的，调用结束后作为独立的输出返回，即 `videos` 和 `audio`，此外还有音轨所携带的 `sampling_rate`；将它们混流到同一个文件中由调用方自行处理，例如使用 [encode_video()](/docs/diffusers/v0.43.0/zh/api/utilities#diffusers.utils.encode_video)。

## 全量参考

`ref2va` 工作流以有序参考列表作为条件：最多 9 张图片、3 个视频和 3 个音频片段，总计 12 个。该顺序具有语义意义。它用于标记提示词呈现中的参考项（`"<Picture 1>"`、`"<Audio 1>"`、`"<Video 1>"`），并推进共享的音频/视频旋转时钟，因此重新排列相同的参考项将构成不同的请求。

与上述关键帧不同，参考图不会约束生成的几何结构：它们以自身的分辨率进行编码，而目标画布默认采用 MiniMax-H3 的 16:9 比例。

每种模态都有一个参考类，每个类都持有内存中的媒体以及媒体所承载的速率：

| 参考 | 媒体 | 它声明的速率 |
| --- | --- | --- |
| [MiniMaxH3ImageReference](/docs/diffusers/v0.43.0/zh/api/pipelines/minimax_h3#diffusers.modular_pipelines.minimax_h3.MiniMaxH3ImageReference) | `image` | — |
| [MiniMaxH3VideoReference](/docs/diffusers/v0.43.0/zh/api/pipelines/minimax_h3#diffusers.modular_pipelines.minimax_h3.MiniMaxH3VideoReference) | `frames`，以及用于其自身音轨的 `audio` | `fps`，默认为 MiniMax-H3 的 24.0，以及 `sample_rate` |
| [MiniMaxH3AudioReference](/docs/diffusers/v0.43.0/zh/api/pipelines/minimax_h3#diffusers.modular_pipelines.minimax_h3.MiniMaxH3AudioReference) | `audio` | `sample_rate`，默认为音频 VAE 自身的 |

这些速率是所有内容重采样的基准：帧会被丢弃或整帧复制，以重采样至 MiniMax-H3 自身的 24 fps；波形则会被重采样至音频 VAE 的采样率。以 MiniMax-H3 自身速率生成的媒体数据会原样通过，因此只有以其他速率生成的数据才需要显式声明其速率。

引用（reference）的构建方式有两种：一是通过该类的 `from_file` 类方法从媒体文件解码得到；二是直接由请求中已驻留内存的媒体数据构建——这正是上一代生成结果回传的方式（参见 [将生成结果作为引用](#a-generation-as-a-reference)）。

这些块从不打开媒体文件——解码路径是调用方的职责，这与库中其他地方的做法一致。每个引用类都通过其 `from_file` 类方法来实现这一点，该方法接受一个路径或 URL（视频和音频通过 [PyAV](https://github.com/PyAV-Org/PyAV) 处理），并返回一个携带容器所报告速率的引用——视频会连同其帧率和音轨一起返回。请优先使用 `from_file` 而非 [load_video()](/docs/diffusers/v0.43.0/zh/api/utilities#diffusers.utils.load_video)，因为后者会丢弃帧率：如果基于帧构建的引用丢失了真实的帧率，它将以错误的速度进行条件化，且不会引发任何错误。

```py
import torch
from diffusers import ComponentsManager, ModularPipeline
from diffusers.modular_pipelines.minimax_h3 import (
    MiniMaxH3AudioReference,
    MiniMaxH3ImageReference,
    MiniMaxH3VideoReference,
)
from diffusers.utils import load_video
from diffusers.utils.export_utils import encode_video

# `ref2va` is a workflow of the one MiniMax-H3 pipeline; selecting it loads only the `transformer_ref/`
# checkpoint partition, and the manager moves each component on and off the accelerator in turn.
manager = ComponentsManager()
manager.enable_auto_cpu_offload(device="cuda")  # or "mps", "xpu", "cpu"

pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3", workflow="ref2va", components_manager=manager)
pipe.load_components(dtype=torch.bfloat16)

subject = MiniMaxH3ImageReference.from_file(
    "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/astronaut.jpg"
)

# Decoding a file brings its rates along: the video its own frame rate and its soundtrack, the clip its sample rate.
results = pipe(
    prompt="The character speaks in time with the reference recording, natural lip movement",
    references=[
        subject,
        MiniMaxH3VideoReference.from_file(
            "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/hiker.mp4"
        ),
        MiniMaxH3AudioReference.from_file("voice.wav"),
    ],
    num_frames=124,
    output=["videos", "audio", "sampling_rate"],
)

# Frames a request already holds declare the rate they carry — `load_video` does not preserve it.
motion = load_video("motion_ref.mp4")
results = pipe(
    prompt="The subject walks toward camera, matching the reference video's shot rhythm",
    references=[subject, MiniMaxH3VideoReference(frames=motion, fps=30.0)],
    num_frames=124,
    output=["videos", "audio", "sampling_rate"],
)

encode_video(
    results["videos"][0],
    fps=24,
    output_path="minimax_h3_ref2va.mp4",
    audio=results["audio"][0],
    audio_sample_rate=results["sampling_rate"],
)
```

`num_frames` 是 `ref2va` 的必填参数。若要生成与参考音轨时长完全一致的视频，请根据片段计算该值——`round(samples / sample_rate * 24)`——该值会被向上取整到视频 VAE 可解码的下一个 `17 * n + 5`；最终时长必须保持在 MiniMax-H3 可生成的 5 至 15 秒范围内。

### 作为参考的生成

由于这些工作流共享同一条流水线，`t2va` 生成的内容可以直接作为 `ref2va` 的参考输入——而内存构造函数正是为这种衔接而设计的。生成的媒体已经处于 MiniMax-H3 自身的速率下（帧率为 24 fps，音轨为音频 VAE 的采样率），因此参考输入无需指定速率参数，在传输过程中也不会经过有损容器进行重新编码：

```py
import torch
from diffusers import ComponentsManager, ModularPipeline
from diffusers.modular_pipelines.minimax_h3 import MiniMaxH3VideoReference

manager = ComponentsManager()
manager.enable_auto_cpu_offload(device="cuda")  # or "mps", "xpu", "cpu"

# The full pipeline holds every workflow and picks one per call from the inputs. Loading without a
# `workflow=` brings both transformer partitions in one call, so the `ref2va` request that follows the
# `t2va` generation needs no further loading.
pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3", components_manager=manager)
pipe.load_components(dtype=torch.bfloat16)

results = pipe(
    prompt="An astronaut hiking through the mountains, humming a tune",
    num_frames=124,
    output=["videos", "audio", "sampling_rate"],
)

reference = MiniMaxH3VideoReference(
    frames=results["videos"][0],
    audio=results["audio"][0],
    sample_rate=results["sampling_rate"],
)
results = pipe(
    prompt="The same astronaut now walks along a beach at sunset, humming the same tune",
    references=[reference],
    num_frames=124,
    output=["videos", "audio", "sampling_rate"],
)
```

## MiniMaxH3ModularPipeline[[diffusers.MiniMaxH3ModularPipeline]]

#### diffusers.MiniMaxH3ModularPipeline[[diffusers.MiniMaxH3ModularPipeline]]

```python
diffusers.MiniMaxH3ModularPipeline(blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = None, pretrained_model_name_or_path: str | os.PathLike | None = None, components_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = None, collection: str | None = None, workflow: str | None = None, modular_config_dict: dict[str, typing.Any] | None = None, config_dict: dict[str, typing.Any] | None = None, **kwargs)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/minimax_h3/modular_pipeline.py#L150)

用于 MiniMax-H3 的联合视频 + 音频生成的 ModularPipeline：`t2va`（仅文本）和 `fl2va`（首帧和/或尾帧）工作流对应 `transformer/` 检查点分区，`ref2va`（全参考）工作流对应 `transformer_ref/`。一个仓库包含这两个分区，选择某个工作流时仅加载其

own:

```py
pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3", workflow="ref2va")
```

MiniMax-H3 对**一条打包序列**进行去噪，该序列同时包含文本条件、关键帧条件潜变量、音频潜变量和视频潜变量。正因如此，各模块传递的是行布局，而非按模态划分的张量；同时，流水线携带两个调度器（视频使用 `shift = 12.0`，音频使用 `shift = 3.0`），并在单次 transformer 调用中分别步进。

该检查点经过引导蒸馏：引导已融入权重中，因此不存在 guider，也没有 `negative_prompt` 和 `guidance_scale`，每一步仅执行一次前向传播。

MiniMax-H3 仅支持模块化：该流水线及其各个模块构成了完整的集成，不存在 `DiffusionPipeline` 的半成品。此模块承载了每个模块所依赖的模型事实——由配置派生的几何信息以属性形式提供，画布和帧数计算以函数形式提供——而条件、编码和噪声契约则定义在模块本身之上。

```py
import torch
from diffusers import ModularPipeline

pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3")
pipe.load_components(dtype=torch.bfloat16)
```

## MiniMaxH3Blocks[[diffusers.MiniMaxH3Blocks]]

#### diffusers.MiniMaxH3Blocks[[diffusers.MiniMaxH3Blocks]]

```python
diffusers.MiniMaxH3Blocks()
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/minimax_h3/modular_blocks_minimax_h3.py#L659)

用于 MiniMax-H3 联合视频 + 音频生成的 Auto Modular 流水线模块：包括 `t2va`（仅文本）、`fl2va`（首帧和/或尾帧关键帧）以及 `ref2va`（全参考）工作流，根据 `references` 和关键帧输入进行选择。如果不指定 `workflow=`，加载组件时会拉取 **两个** 61.7GB 的 transformer 分区——请传入其中一个，以仅加载任务所需的部分。

支持的工作流：
- `t2va`：需要 `prompt`
- `fl2va`：需要 `prompt`、`image` 或 `prompt`、`last_image`
- `ref2va`：需要 `prompt`、`references`

组件：image_processor (`VaeImageProcessor`) text_encoder (`Qwen3VLForConditionalGeneration`) tokenizer (`Qwen2Tokenizer`) processor (`Qwen3VLProcessor`) vae (`AutoencoderKLMiniMaxH3`) audio_vae (`AutoencoderKLMiniMaxH3Audio`) scheduler (`MiniMaxH3Scheduler`) audio_scheduler (`MiniMaxH3Scheduler`) transformer_ref (`MiniMaxH3Transformer3DModel`) transformer (`MiniMaxH3Transformer3DModel`) video_processor (`VideoProcessor`)

配置项：canvas_short_edge（默认值：768）canvas_max_pixels（默认值：1032192）reference_image_short_edge（默认值：2048）

Inputs: references (`list`, *可选*): 用于条件化的参考素材，**按模型应读取的顺序排列**：该顺序决定了提示词呈现中的标签顺序，并决定了它们在共享旋转时钟上的布局，因此不同的顺序代表不同的请求。每种模态对应一个数据类，均持有内存中的媒体数据——一个 `MiniMaxH3ImageReference`（最多 9 个）、一个以其自身 `fps` 为单位的 `MiniMaxH3VideoReference`（最多 3 个，其 `audio` 音轨也会作为条件），或一个以其自身 `sample_rate` 为单位的 `MiniMaxH3AudioReference`（最多 3 个）——参考素材总数最多为 12 个，且音频参考不能是唯一存在的参考。这些块从不打开媒体文件：请使用每个类的 `from_file` 类方法来解码，该方法会一并带入相应的采样率。height (`int`, *可选*): 生成视频的高度（以像素为单位），必须是 32 的倍数。width (`int`, *可选*): 生成视频的宽度（以像素为单位），必须是 32 的倍数。num_frames (`int`, *可选*): 要生成的帧数，固定为 24 fps。该值会向上取整到视频 VAE 可解码的下一个 `17 * n + 5`；生成的时长必须保持在 5 到 15 秒之间。若要生成与参考音轨一样长的视频，请传入 `round(samples / sample_rate * 24)`。image (`Image`, *可选*): 视频起始的关键帧。它会被*拉伸*到目标画布上，该画布默认由其自身的宽高比推导得出。last_image (`Image`, *可选*): 视频结束的关键帧。可以单独传入以生成*直至*某一帧的视频。与 `image` 结合使用时，它是两者中的跟随者，并会被裁剪以覆盖画布。prompt (`str`): 用于引导生成的提示词，为单个字符串。normalized_references (`list`, *可选*): 由设置步骤归一化后的参考素材，按打包顺序排列。keyframes (`list`, *可选*): 放置在目标画布上的关键帧，按打包顺序排列。condition_latents (`list`, *可选*): 编码后的视频条件潜变量，按打包顺序每个图像和视频参考对应一个。它们的形状决定了每个参考块的几何信息。audio_condition_latents (`list`, *可选*): 编码后的音频条件行，按打包顺序每个包含音频的参考对应一个。generator (`Generator`, *可选*): 请求的生成器。条件噪声首先从中抽取，每个条件抽取一次，然后才是生成行的噪声。latents (`Tensor`): 形状为 `(1, 24, num_latent_frames, latent_height, latent_width)` 的预生成视频噪声，用于替代随机抽取。audio_latents (`Tensor`): 形状为 `(2, 32, num_audio_latents)` 的预生成音频噪声。num_inference_steps (`int`, *可选*, 默认为 50): 去噪步数。**denoiser_input_fields (`None`, *可选*): Transformer 按名称读取的打包序列的结构描述：`token_tags`、`position_ids` 以及三个行索引张量。attention_kwargs (`dict`, *可选*): 用于注意力处理器的额外 kwargs。keyframe_anchors (`tuple`, *可选*, 默认为 ()): 每个关键帧锚定到视频的哪一端，按打包顺序排列。output_type (`str`, *可选*, 默认为 pil): 输出格式：'pil'、'np' 或 'pt'。

输出：videos (`list`)：生成的视频。audio (`Tensor`)：生成的音轨，形状为 `(1, 2, num_samples)`。sampling_rate (`int`)：生成音轨的采样率，单位为 Hz。

## MiniMaxH3ImageReference[[diffusers.modular_pipelines.minimax_h3.MiniMaxH3ImageReference]]

#### diffusers.modular_pipelines.minimax_h3.MiniMaxH3ImageReference[[diffusers.modular_pipelines.minimax_h3.MiniMaxH3ImageReference]]

```python
diffusers.modular_pipelines.minimax_h3.MiniMaxH3ImageReference(image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor])
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/minimax_h3/references.py#L82)

**参数：**

image (`PIL.Image.Image`、`np.ndarray` 或 `torch.Tensor`)：参考图像：一张图像、一个 `(height, width, 3)` 数组或一个 `(3, height, width)` 张量，数据类型为 `uint8` 或 `[0, 1]` 范围内的浮点数。它不会绑定生成的几何结构——它会在自身的一个短边上进行编码，对于已发布的检查点，该短边为 2048，无论请求生成的画布尺寸如何。

主题、风格或场景参考：每次请求最多 9 个。

#### from_file[[diffusers.modular_pipelines.minimax_h3.MiniMaxH3ImageReference.from_file]]

```python
from_file(media)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/minimax_h3/references.py#L98)

**参数：**

media (`str` 或 `os.PathLike`)：图像的路径或 URL。

通过 [load_image()](/docs/diffusers/v0.43.0/zh/api/utilities#diffusers.utils.load_image) 将图像文件加载到 `MiniMaxH3ImageReference` 中。

## MiniMaxH3VideoReference[[diffusers.modular_pipelines.minimax_h3.MiniMaxH3VideoReference]]

#### diffusers.modular_pipelines.minimax_h3.MiniMaxH3VideoReference[[diffusers.modular_pipelines.minimax_h3.MiniMaxH3VideoReference]]

```python
diffusers.modular_pipelines.minimax_h3.MiniMaxH3VideoReference(frames: typing.Union[list[PIL.Image.Image], numpy.ndarray, torch.Tensor], fps: float | None = None, audio: typing.Optional[torch.Tensor] = None, sample_rate: int | None = None)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/minimax_h3/references.py#L110)

**参数：**

frames (`list[PIL.Image.Image]`、`np.ndarray` 或 `torch.Tensor`)：参考帧：一个图像列表、一个 `(num_frames, height, width, 3)` 数组或一个 `(num_frames, 3, height, width)` 张量，数据类型为 `uint8` 或 `[0, 1]` 范围内的浮点数。

fps (`float`, *可选*，默认值为 24.0) : `frames` 所携带的帧率，该帧率决定了参考视频的视觉块如何对齐到条件器的 2 fps 网格上。MiniMax-H3 自身的时钟为 24 fps，因此任何其他帧率都会通过丢弃和复制完整帧的方式重采样到 24 fps——当帧数据来自文件时，务必确保此参数设置正确。

audio (`torch.Tensor`，形状为 `(channels, num_samples)`，*可选*)：该视频的音轨，单声道或立体声，作为参考自身的条件，而非作为其自身的参考条件。若省略此项，则参考仅以运动作为条件。

sample_rate (`int`, *可选*) : `audio` 所承载样本的采样率。若省略，则使用音频 VAE 自身的采样率，样本将保持不变；若指定其他采样率，则会将其重采样到该值。

动作和相机参考：每个请求最多 3 个，与其自身的音轨一起作为条件。

#### from_file[[diffusers.modular_pipelines.minimax_h3.MiniMaxH3VideoReference.from_file]]

```python
from_file(media)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/minimax_h3/references.py#L146)

**参数：**

media (`str` 或 `os.PathLike`)：视频的路径或 URL。

**返回：** `MiniMaxH3VideoReference`

以容器报告的帧率返回 `(num_frames, height, width, 3)` 形状的 `uint8` 帧，如果包含音频流，则同时携带其音轨及该音轨自身的采样率。

将视频文件解码为 `MiniMaxH3VideoReference`，保留其分辨率、帧率和音轨。

速率会落在 reference 上，这正是采用这种方式而非 [load_video()](/docs/diffusers/v0.43.0/zh/api/utilities#diffusers.utils.load_video) 进行解码的意义所在：MiniMax-H3 会将 reference 重采样为其自身的 24 fps，因此输入过程中丢失的帧率意味着请求是在错误的速度下进行的条件设定，且没有任何机制会对此发出警告。如果容器的元数据有误，可以通过在返回的 reference 上覆盖 `fps` 或 `sample_rate` 来加以修正。

需要 [PyAV](https://github.com/PyAV-Org/PyAV)。

## MiniMaxH3AudioReference[[diffusers.modular_pipelines.minimax_h3.MiniMaxH3AudioReference]]

#### diffusers.modular_pipelines.minimax_h3.MiniMaxH3AudioReference[[diffusers.modular_pipelines.minimax_h3.MiniMaxH3AudioReference]]

```python
diffusers.modular_pipelines.minimax_h3.MiniMaxH3AudioReference(audio: Tensor, sample_rate: int | None = None)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/minimax_h3/references.py#L172)

**参数：**

audio (`torch.Tensor`，形状为 `(channels, num_samples)`)：参考波形，单声道或立体声。

sample_rate (`int`, *可选*) : `audio` 所承载样本的采样率。若省略，则使用音频 VAE 自身的采样率，样本将保持不变；若指定其他采样率，则会将其重采样到该值。

语音或音乐参考：每次请求最多 3 个，且不能单独使用——音频参考必须与至少一个图像或视频参考配对。它不会到达 conditioner，而是仅由音频 VAE 进行编码。

#### from_file[[diffusers.modular_pipelines.minimax_h3.MiniMaxH3AudioReference.from_file]]

```python
from_file(media)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/minimax_h3/references.py#L191)

**参数：**

media (`str` 或 `os.PathLike`)：音频的路径或 URL，或提取音轨的视频的路径或 URL。

**返回：** `MiniMaxH3AudioReference`

容器所报告采样率下的 `(channels, num_samples)` float32 波形。

将音频文件解码为 `MiniMaxH3AudioReference`，并保留其采样率。

需要 [PyAV](https://github.com/PyAV-Org/PyAV)。