# MiniMax-H3

  
    
  

MiniMax-H3 генерирует видео и его звуковую дорожку одновременно. Единый трансформер выполняет денойзинг одной упакованной последовательности, содержащей текстовые условия, медиа для условий, а также целевые латенты видео и аудио. Отдельный вокодер и последующая обработка аудио отсутствуют: видео и аудио получаются в рамках одного и того же цикла денойзинга.

Оригинальные контрольные точки MiniMax-H3 можно найти в организации [MiniMaxAI](https://huggingface.co/MiniMaxAI).

MiniMax-H3 интегрируется только в виде блоков [Modular Diffusers](../../modular_diffusers/overview), так же, как и [Anima](./anima): сами блоки и их [MiniMaxH3ModularPipeline](/docs/diffusers/main/ru/api/pipelines/minimax_h3#diffusers.MiniMaxH3ModularPipeline) составляют всю интеграцию, и части `DiffusionPipeline` здесь нет.

## Раскладка контрольной точки

MiniMax-H3 был выпущен в виде двух разделов контрольных точек, которые разделяют все компоненты, кроме трансформера, поэтому конвертация в diffusers помещает оба в **одно репозиторий**:

| Подпапка | Рабочие процессы |
|---|---|
| `transformer/` | `t2va` (только текст), `fl2va` (первый и/или последний ключевой кадр) |
| `transformer_ref/` | `ref2va` (упорядоченная смесь ссылок на изображения, видео и аудио) |

Всё, кроме трансформера, а именно видео-VAE, аудио-VAE, кондиционер Qwen3-VL, его токенизатор и процессор, а также два планировщика, является общим и хранится один раз.

Кондиционером является `Qwen3VLForConditionalGeneration`, а MiniMax-H3 читает *ненормализованное* скрытое состояние после 50-го слоя декодера, а не последнего, поэтому используется полный опубликованный чекпоинт, при этом его головная часть языковой модели не задействуется.

Все три задачи представляют собой рабочие процессы единого [MiniMaxH3Blocks](/docs/diffusers/main/ru/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")
```

Загрузка *loading* по-прежнему может выполняться по одному рабочему процессу за раз. Этот один вызов загружает `transformer/` и все общие компоненты, которые используются как в `t2va`, так и в `fl2va`:

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

Обычный вызов `load_components()` без параметра `workflow=` загружает **оба** раздела трансформера по 61,7 ГБ, что позволяет одному конвейеру обслуживать все три сценария без повторного вызова загрузки. В сочетании с [ComponentsManager](/docs/diffusers/main/ru/api/modular_diffusers/pipeline_components#diffusers.ComponentsManager) и автоматическим выгрузкой (offloading) веса хранятся в оперативной памяти хоста, а менеджер переносит на ускоритель только то, что требуется на каждом шаге: когда денуизеру `ref2va` требуется устройство, стратегия выгрушает то, что освобождает достаточно места. Рецепты описаны в разделе [Память](#memory).

## Два планировщика

Видео- и аудиолатенты на каждом шаге внутри одного вызова трансформера следуют по двум разным расписаниям, поэтому блоки ожидают два экземпляра [MiniMaxH3Scheduler](/docs/diffusers/main/ru/api/schedulers/minimax_h3#diffusers.MiniMaxH3Scheduler): `scheduler` для видеолатентов (`shift=12.0` в выпущенных контрольных точках) и `audio_scheduler` для аудиолатентов (`shift=3.0`).

Обе трансформерные партиции прошли дистилляцию с использованием guidance, поэтому это верно для любого рабочего процесса: guidance вшит в веса, guider отсутствует, как и `negative_prompt` и `guidance_scale`, а на каждом шаге выполняется ровно один прямой проход.

## Ограничения генерации

- **24 fps, от 5 до 15 секунд.** Значение `num_frames` округляется вверх до ближайшего числа вида `17 * n + 5`, которое может декодировать видео-VAE, при этом итоговая длительность должна оставаться в указанном диапазоне.
- **Короткая сторона 768 пикселей.** Параметры `height` и `width` по умолчанию соответствуют собственному холсту MiniMax-H3 для соотношения сторон первого ключевого кадра (или 16:9, если его нет) и должны быть кратны 32.
- **Один генератор, три выборки.** Запрос сначала извлекает шум для ключевых кадров или референсного условия, затем шум для видео, затем шум для аудио — всё из переданного ему `generator`, поэтому два запуска из одного и того же состояния генератора возвращают одинаковое видео и звуковую дорожку. Передача `latents` или `audio_latents` заменяет соответствующую выборку.
- **`num_inference_steps` учитывает точки сетки сигм**, включая конечную `0`, поэтому на одно вычисление модели меньше.

## Память

Сам трансформатор занимает 61,7 ГБ в bfloat16, а conditioner Qwen3-VL — ещё 62,1 ГБ, поэтому способ загрузки зависит от аппаратного обеспечения. Уменьшение холста — самый мощный рычаг ускорения на любой конфигурации: `height` и `width` должны быть кратны 32, а разрешение 960x544 выполняется примерно в 2,3 раза быстрее на каждом шаге по сравнению с обученным разрешением 1344x768.

На одной карте на 80 ГБ зарегистрируйте компоненты в [ComponentsManager](/docs/diffusers/main/ru/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 ГБ) квантуйте два крупных компонента до int8 при загрузке и передавайте блоки трансформера из оперативной памяти CPU. Всё, что описано ниже, использует только поддерживаемые загрузчики, не требует патчей и работает напрямую из контрольной точки 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 ГБ тот же рецепт работает и с выгруженной группой видео-VAE (`offload_type="leaf_level"`, без потока) и с небольшим холстом, например 960x544. Ожидайте, что веса будут находиться в оперативной памяти хоста: около 75 ГБ при int8.

При наличии двух карт ничего не нужно выгружать: разделите конвейер пополам и разместите каждую половину на своём устройстве.

```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 ГБ запускают полную модель в bfloat16 следующим образом: каждая половина помещается на свою карту, поэтому после загрузки в память ничего не выгружается обратно в память хоста. Две карты по 48 ГБ делают то же самое с загрузкой int8, описанной выше, для обоих компонентов.

## Текст и ключевые кадры

[MiniMaxH3Blocks](/docs/diffusers/main/ru/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/main/ru/api/utilities#diffusers.utils.encode_video).

## Омни-ссылки

Рабочий процесс `ref2va` использует в качестве условия упорядоченный список эталонных данных: до 9 изображений, 3 видео и 3 аудиоклипов, всего 12. Порядок имеет семантическое значение. Он определяет метки эталонных данных в представлении промпта (`"<Picture 1>"`, `"<Audio 1>"`, `"<Video 1>"`) и сдвигает общую аудио/видео ротационную шкалу времени, поэтому изменение порядка тех же эталонных данных представляет собой другой запрос.

В отличие от ключевых кадров выше, референсы не ограничивают генерируемую геометрию: они кодируются в собственном разрешении, а целевой холст по умолчанию имеет соотношение сторон 16:9, как у MiniMax-H3.

Для каждой модальности существует один класс-ссылка, каждый из которых хранит медиа в памяти и частоту, с которой передаются медиа:

| справочник | media | скорость, которую он объявляет |
| --- | --- | --- |
| [MiniMaxH3ImageReference](/docs/diffusers/main/ru/api/pipelines/minimax_h3#diffusers.modular_pipelines.minimax_h3.MiniMaxH3ImageReference) | `image` | — |
| [MiniMaxH3VideoReference](/docs/diffusers/main/ru/api/pipelines/minimax_h3#diffusers.modular_pipelines.minimax_h3.MiniMaxH3VideoReference) | `frames` и `audio` для собственного звукового сопровождения | `fps`, по умолчанию 24.0 для MiniMax-H3, и `sample_rate` |
| [MiniMaxH3AudioReference](/docs/diffusers/main/ru/api/pipelines/minimax_h3#diffusers.modular_pipelines.minimax_h3.MiniMaxH3AudioReference) | `audio` | `sample_rate`, по умолчанию — собственная частота дискретизации аудио-VAE |

Скорости — это то, от чего происходит вся пересэмплирование: кадры приводятся к собственным 24 fps модели MiniMax-H3 путём удаления и дублирования целых кадров, а волновая форма — к частоте дискретизации аудио-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/main/ru/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)` — и он будет округлён вверх до ближайшего значения вида `17 * n + 5`, которое может декодировать видео-VAE; итоговая длительность должна оставаться в пределах от 5 до 15 секунд, которые генерирует MiniMax-H3.

### Поколение как эталон

Поскольку рабочие процессы используют один и тот же конвейер, результат генерации `t2va` можно сразу передать в качестве эталона для `ref2va` — и конструктор в памяти создан именно для такой передачи. Сгенерированные медиа уже соответствуют собственным частотам MiniMax-H3 (кадры с частотой 24 к/с, звуковой дорожки — частоте дискретизации аудио-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/main/src/diffusers/modular_pipelines/minimax_h3/modular_pipeline.py#L150)

Модульный `t2va` для совместной генерации видео и аудио с MiniMax-H3: рабочие процессы `t2va` (только текст) и `fl2va` (первый и/или последний ключевой кадр) для раздела контрольных точек `transformer/`, а также рабочий процесс `ref2va` (омни-референс) для `transformer_ref/`. В одном репозитории хранятся оба раздела, и при выборе рабочего процесса загружается только его

собственный:

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

MiniMax-H3 выполняет денойзинг **одной упакованной последовательности**, которая одновременно содержит текстовые условия, латенты условий ключевых кадров, аудио-латенты и видео-латенты. Именно поэтому блоки передают между собой строковое расположение данных, а не тензоры по отдельным модальностям, и почему пайплайн использует два планировщика (`shift = 12.0` для видео и `shift = 3.0` для аудио), шаги которых выполняются в рамках одного вызова трансформера.

Чекпоинт получен с дистилляцией guidance: guidance «запечён» в весах, поэтому нет 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/main/src/diffusers/modular_pipelines/minimax_h3/modular_blocks_minimax_h3.py#L659)

Блоки модульного конвейера Auto для совместной генерации видео и аудио с MiniMax-H3: рабочие процессы `t2va` (только текст), `fl2va` (первый и/или последний ключевой кадр) и `ref2va` (omni-reference), выбор которых осуществляется на основе входных данных `references` и ключевых кадров. Если не указано `workflow=`, при загрузке компонентов будут загружены **оба** раздела трансформера размером 61,7 ГБ — передайте один из них, чтобы загрузить только то, что требуется для задачи.

Поддерживаемые рабочие процессы:
- `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`, *необязательный*): Ссылки, на которые опирается генерация, **в том порядке, в котором модель должна их читать**: порядок определяет их метки в представлении промпта и расположение на общей вращательной шкале, поэтому другой порядок — это другой запрос. По одному dataclass на модальность, все хранят медиа в памяти: `MiniMaxH3ImageReference` (не более 9), `MiniMaxH3VideoReference` со своей частотой `fps` (не более 3, звуковой дорожке `audio` также задается условие), или `MiniMaxH3AudioReference` со своей частотой `sample_rate` (не более 3) — всего не более 12 ссылок, при этом ссылки на аудио не могут быть единственными. Эти блоки никогда не открывают медиафайл: декодируйте с помощью classmethod `from_file` каждого класса, который также передает частоты. height (`int`, *необязательный*): Высота генерируемого видео в пикселях, кратная 32. width (`int`, *необязательный*): Ширина генерируемого видео в пикселях, кратная 32. num_frames (`int`, *необязательный*): Количество кадров для генерации при фиксированной частоте 24 fps. Значение округляется вверх до ближайшего `17 * n + 5`, которое может декодировать видео VAE; итоговая длительность должна оставаться в пределах от 5 до 15 секунд. Чтобы сгенерировать видео такой же длины, как референсная звуковая дорожка, передайте `round(samples / sample_rate * 24)`. image (`Image`, *необязательный*): Ключевой кадр, с которого начинается видео. Он *растягивается* на целевое полотно, которое по умолчанию выводится из его собственного соотношения сторон. last_image (`Image`, *необязательный*): Ключевой кадр, на котором заканчивается видео. Можно передать отдельно, чтобы сгенерировать *до* кадра. В сочетании с `image` он является вторым из пары и обрезается по охвату (cover-crop) на полотно. 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`, *необязательный*): Структурное описание упакованной последовательности, которую трансформер читает по имени: `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`): частота дискретизации сгенерированной звуковой дорожки в Гц.

## 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/main/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/main/src/diffusers/modular_pipelines/minimax_h3/references.py#L98)

**Параметры:**

media (`str` или `os.PathLike`) : Путь или URL изображения.

Загрузите файл изображения в `MiniMaxH3ImageReference` с помощью [load_image()](/docs/diffusers/main/ru/api/utilities#diffusers.utils.load_image).

## 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/main/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`, *optional*, по умолчанию 24.0) : Частота кадров, которую несёт `frames`, и именно она определяет, как блоки зрения референса размещаются на сетке 2 fps кондиционера. Собственная частота MiniMax-H3 составляет 24 fps, поэтому любая другая частота приводится к ней путём удаления и дублирования целых кадров — поэтому это поле важно указать правильно, если кадры получены из файла.

audio (`torch.Tensor` формы `(channels, num_samples)`, *необязательный*) : Саундтрек данного видео, моно или стерео, используемый в качестве условия как собственный, а не как ссылка на собственный. Если не указан, условием служит только движение.

sample_rate (`int`, *optional*) : Частота, с которой `audio` несёт свои сэмплы. Если не указано, используется собственная частота аудио-VAE, и сэмплы остаются без изменений; любая другая частота приводит к ресемплированию на неё.

Ссылка на движение и камеру: не более 3 на запрос, с условием, что они обрабатываются вместе со своим звуковым сопровождением.

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

```python
from_file(media)
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/minimax_h3/references.py#L146)

**Параметры:**

media (`str` или `os.PathLike`) : Путь или URL видео.

**Возвращает:** `MiniMaxH3VideoReference`

кадры `(num_frames, height, width, 3)` типа `uint8` с частотой кадров, указанной в контейнере, с его звуковым сопровождением и собственной частотой дискретизации этого сопровождения, если в контейнере есть аудиопоток.

Декодирование видеofайла в `MiniMaxH3VideoReference` с сохранением разрешения, частоты кадров и звукового сопровождения.

Частоты попадают в reference, что и является целью такого способа декодирования, а не [load_video()](/docs/diffusers/main/ru/api/utilities#diffusers.utils.load_video): MiniMax-H3 пересэмплирует reference под собственные 24 fps, поэтому потерянная по пути частота кадров означает запрос, сформированный с неверной скоростью, и система не выдаст об этом никакого предупреждения. Если метаданные контейнера неверны, это исправляется переопределением `fps` или `sample_rate` в возвращаемом reference.

Требуется [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/main/src/diffusers/modular_pipelines/minimax_h3/references.py#L172)

**Параметры:**

audio (`torch.Tensor` формы `(channels, num_samples)`) : эталонная волна, моно или стерео.

sample_rate (`int`, *optional*) : Частота, с которой `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/main/src/diffusers/modular_pipelines/minimax_h3/references.py#L191)

**Параметры:**

media (`str` или `os.PathLike`) : путь или URL к аудиофайлу или к видео, из которого извлекается звуковая дорожка.

**Возвращает:** `MiniMaxH3AudioReference`

float32-волну `(channels, num_samples)` с частотой дискретизации, указанной в контейнере.

Декодирование аудиофайла в `MiniMaxH3AudioReference` с частотой дискретизации, указанной в файле.

Требуется [PyAV](https://github.com/PyAV-Org/PyAV).