MiniMax H3 Turbo

Video with its own stereo audio at 768p, in a schedule short enough to iterate on. The same H3-Base weights as the standard entry, served through the step-distilled adapter lightx2v publish for it, which is what the model's own ComfyUI workflow runs and what their own service deploys. A clip takes about a fifth as long as the base model needs for the same length.

Video generationrtx-pro-6000MiniMaxMiniMax licenseMiniMaxAI/MiniMax-H3

What runs

This is the whole app. The entry names the model and what serves it, and the build turns that into these files: there is nothing else to write.

model.py
"""MiniMax H3 Turbo, generated from a declarative template."""

from __future__ import annotations

import base64
import os
import tempfile
from typing import Literal

from pydantic import BaseModel, ConfigDict, Field, model_validator

from runware_serverless import serve

MODEL = "MiniMaxAI/MiniMax-H3"
REVISION = "42ed227ee7df40d41602854ae760620d6eb651fe"
CACHE = "/weights"
FPS = 24
TOKEN_BUDGET = 262080
FRAME_BLOCK = 17
FRAME_BASE = 5
TURBO_REPO = "lightx2v/Minimax-h3-Turbo"
TURBO = "minimax_h3_fl2v_turbo_8step_v1.0_768p_bf16.safetensors"
LORA_TARGETS = ("to_q", "to_k", "to_v", "to_out.0", "ff.net.0.proj", "ff.net.2")

# The grid the adapter was distilled on, which its own filename carries: the
# 768p checkpoints were trained at 6 and 3, the 544p ones at 12 and 3.
VIDEO_SHIFT = 6.0
AUDIO_SHIFT = 3.0
DEFAULT_FRAMES = 124
TRAINED_SHORT_EDGE = 768
TRAINED_WIDTH = 1344

# The model's own API names a canvas by its short edge and an aspect ratio, and
# this follows it, so every canvas is a multiple of 32 and none of them has to be
# refused. The patch size is 32 along height and width.
RATIOS = {"16:9": (16, 9), "9:16": (9, 16), "1:1": (1, 1), "4:3": (4, 3), "3:4": (3, 4)}


def _canvas(aspect: str, short_edge: int) -> tuple[int, int]:
    wide, tall = RATIOS[aspect]
    if wide >= tall:
        return (short_edge * wide // tall) // 32 * 32, short_edge
    return short_edge, (short_edge * tall // wide) // 32 * 32


class Request(BaseModel):
    # An input this model does not read is a line the caller believed was doing
    # something, so it is refused rather than dropped. Without this, pydantic
    # ignores it: a width sent to a model of fixed size, or a misspelled seed,
    # both come back as a result that silently answered a different request.
    model_config = ConfigDict(extra="forbid")

    prompt: str = Field(description="What to generate, as video with its own audio.")
    frames: int = Field(
        default=DEFAULT_FRAMES,
        ge=124,
        le=345,
        description=(
            "At 24 fps. The model snaps this up to the next length of the form 17n+5,"
            " which its video VAE decodes in blocks, so 124 is the floor and 345 the"
            " ceiling that stays inside the five to fifteen seconds it generates."
        ),
    )
    steps: int = Field(
        default=9,
        ge=2,
        le=100,
        description=(
            "Denoising steps. This checkpoint is distilled for 8 evaluations of the transformer, which is 9 here because the terminal point of the sigma grid drives none, and 9 is what its publisher serves it at. Moving it either way makes it worse, because the schedule is bent to put those 8 evaluations where they belong and any other count lands them somewhere else, and the whole request scales with"
            " this, because the transformer is nearly all of it. Two is the floor rather than"
            " one, because the step count includes the terminal point of the sigma grid and"
            " that one drives no evaluation."
        ),
    )
    short_edge: int = Field(
        default=TRAINED_SHORT_EDGE,
        ge=512,
        le=TRAINED_SHORT_EDGE,
        multiple_of=32,
        description=(
            "The shorter side of the frame, which the aspect ratio turns into a canvas. The"
            " largest speed lever here and the only one that changes the result: 544 runs at"
            " 2.59 times the speed per step of the trained 768, measured at 124 frames in 16:9."
            " 768 is the ceiling because this is H3-Base."
        ),
    )
    aspect: Literal["16:9", "9:16", "1:1", "4:3", "3:4"] = Field(
        default="16:9",
        description="The ratio the short edge is grown into. 16:9 is what the model trained on.",
    )
    seed: int | None = Field(default=None, description="Repeat a result by repeating its seed.")

    @model_validator(mode="after")
    def _fits_on_the_card(self) -> "Request":
        # Refused here rather than discovered on the card. A clip past what one
        # card holds raises out of memory inside the request, which takes the
        # worker with it, so the caller gets a dead app instead of an answer.
        #
        # One budget covers both axes, because the cost and the peak follow the
        # token count and not how it was split: 175 frames at 1344x768 and 345
        # at 960x544 are within 0.3% of each other on tokens and within 0.6% on
        # time per step.
        width, height = _canvas(self.aspect, self.short_edge)
        blocks = -(-(self.frames - FRAME_BASE) // FRAME_BLOCK)
        tokens = (blocks * FRAME_BLOCK + FRAME_BASE) * (width // 32) * (height // 32)
        if tokens > TOKEN_BUDGET:
            raise ValueError(
                f"{self.frames} frames at {width}x{height} is {tokens} transformer tokens"
                f" and one card holds {TOKEN_BUDGET}. Shorten the clip or lower short_edge:"
                " the two trade against each other, so the same budget buys about 10 seconds"
                " at the trained canvas or about 14 at a 544 short edge."
            )
        return self


class Generated(BaseModel):
    video: str = Field(description="The result as a base64 MP4, with its audio muxed in.")
    frames: int
    width: int
    height: int
    steps: int
    seed: int | None


@serve
class GeneratedVideo:
    def load(self) -> None:
        if hasattr(self, "pipeline"):
            return

        # Imported here rather than at the top of the file. The build imports
        # this file with the platform's own dependencies, so nothing above
        # exists until a worker runs.
        import torch
        from diffusers import ModularPipeline

        self.torch = torch

        self.pipeline = ModularPipeline.from_pretrained(
            MODEL, revision=REVISION, cache_dir=CACHE
        )

        from diffusers import MiniMaxH3Transformer3DModel, TorchAoConfig
        from transformers import Qwen3VLForConditionalGeneration
        from transformers import TorchAoConfig as TransformersTorchAoConfig
        from torchao.quantization import Float8DynamicActivationFloat8WeightConfig

        def recipe() -> object:
            return Float8DynamicActivationFloat8WeightConfig()

        self.pipeline.update_components(
            transformer=MiniMaxH3Transformer3DModel.from_pretrained(
                MODEL,
                subfolder="transformer",
                revision=REVISION,
                cache_dir=CACHE,
                dtype=torch.bfloat16,
                device_map="cuda",
                quantization_config=TorchAoConfig(
                    recipe(),
                    modules_to_not_convert=[
                        "proj_in",
                        "audio_proj_in",
                        "context_embedder",
                        "time_embedder",
                        "time_proj",
                        "token_refiner",
                        "norm_out",
                        "proj_out",
                        "audio_proj_out",
                    ],
                ),
            ),
            text_encoder=Qwen3VLForConditionalGeneration.from_pretrained(
                MODEL,
                subfolder="text_encoder",
                revision=REVISION,
                cache_dir=CACHE,
                dtype=torch.bfloat16,
                device_map="cuda",
                quantization_config=TransformersTorchAoConfig(
                    recipe(),
                    modules_to_not_convert=[
                        "model.visual",
                        "model.language_model.embed_tokens",
                        "model.language_model.norm",
                        "lm_head",
                    ],
                ),
            ),
        )
        # Every component stays on the card. A worker's host RAM is half its
        # card's VRAM, 48 GiB against 96 GiB here, so offloading to the host
        # runs out of memory long before the card does: the kill then comes
        # from the container's cgroup as exit 137, not from torch as a CUDA
        # error, which is why it reads as a platform fault rather than a
        # sizing one.
        self.pipeline.load_components(
            workflow="fl2va", dtype=torch.bfloat16, device_map="cuda"
        )
        self._adapter()

    def _adapter(self) -> None:
        """Load the distillation adapter and bend both schedulers onto its grid.

        Unfused. PEFT wraps the layer rather than rewriting it, so the base
        weight stays the quantized tensor it was and the adapter adds its delta
        in bfloat16 beside it, which is what lets a LoRA sit on a quantized
        model at all. Fusing would have to write into that tensor.

        Every mismatch raises. A half-loaded adapter still produces video, and
        the result is then neither the base model nor the distilled one.
        """
        from huggingface_hub import hf_hub_download
        from peft import LoraConfig
        from safetensors import safe_open

        path = hf_hub_download(TURBO_REPO, TURBO, cache_dir=CACHE)
        with safe_open(path, framework="pt", device="cpu") as handle:
            metadata = handle.metadata() or {}
            state = {key: handle.get_tensor(key) for key in handle.keys()}

        ranks = {
            tensor.shape[0] for key, tensor in state.items()
            if key.endswith(".lora_A.default.weight")
        }
        if len(ranks) != 1:
            raise ValueError(
                f"{TURBO} carries ranks {sorted(ranks)}, and one rank is expected."
            )
        rank = ranks.pop()

        # Read from the file rather than fixed. Effective strength is
        # scale * alpha / rank, and two checkpoints in this repository share a
        # rank of 128 while carrying 8 and 128, so a constant would be a
        # sixteen-fold error in adapter strength on one of them. Missing is
        # refused for the same reason: a fallback is that constant.
        if "alpha" not in metadata:
            raise RuntimeError(
                f"{TURBO} declares no alpha, and its strength cannot be derived from"
                " the weights, so the adapter would be applied at a guessed scale."
            )
        alpha = float(metadata["alpha"])

        transformer = _component(self.pipeline, "transformer")
        transformer.add_adapter(
            LoraConfig(
                r=rank,
                lora_alpha=alpha,
                init_lora_weights=False,
                target_modules=list(LORA_TARGETS),
                use_rslora=False,
            )
        )
        incompatible = transformer.load_state_dict(state, strict=False)
        unfilled = [key for key in incompatible.missing_keys if ".lora_" in key]
        if unfilled or incompatible.unexpected_keys:
            raise RuntimeError(
                f"{TURBO} did not load whole: unfilled={unfilled[:3]},"
                f" unexpected={incompatible.unexpected_keys[:3]}."
            )
        transformer.set_adapters("default", weights=1.0)
        transformer.eval()

        # Not optional, and separate for the two modalities. For N steps the
        # evaluation points are (N - i) / N on the unshifted grid, and the shift
        # moves them onto the one the adapter was distilled on. Without it the
        # adapter denoises off its grid, which produces video and nothing else.
        for name, shift in (("scheduler", VIDEO_SHIFT), ("audio_scheduler", AUDIO_SHIFT)):
            scheduler = _component(self.pipeline, name)
            if scheduler is None or not hasattr(scheduler, "set_shift"):
                raise RuntimeError(
                    f"{name} cannot take a shift, so the adapter would denoise off the grid"
                    " it was distilled on."
                )
            scheduler.set_shift(shift)

    def predict(self, request: Request) -> Generated:
        from diffusers.utils.export_utils import encode_video

        generator = None
        if request.seed is not None:
            generator = self.torch.Generator().manual_seed(request.seed)

        width, height = _canvas(request.aspect, request.short_edge)

        results = self.pipeline(
            prompt=request.prompt,
            num_frames=request.frames,
            num_inference_steps=request.steps,
            width=width,
            height=height,
            generator=generator,
            output=["videos", "audio", "sampling_rate"],
        )

        videos, audio, sampling_rate = _named(results)

        # Both are indexed, because the pipeline returns a batch and the encoder
        # takes one clip. Dropping the batch dimension on the audio matters more
        # than it looks: the encoder treats any shape carrying a 1 as mono and
        # flattens it, so a stereo [1, 2, N] becomes one interleaved channel of
        # 2N and the track plays at twice the length of the picture.
        clip, track = videos[0], audio[0]

        with tempfile.NamedTemporaryFile(suffix=".mp4") as handle:
            encode_video(
                clip,
                fps=FPS,
                output_path=handle.name,
                audio=track,
                audio_sample_rate=sampling_rate,
            )
            handle.seek(0)
            encoded = base64.b64encode(handle.read()).decode("ascii")

        # What came out, not what was asked for. The model rounds the frame
        # count to its own stride, so the two differ.
        return Generated(
            video=encoded,
            frames=len(clip),
            width=width,
            height=height,
            steps=request.steps,
            seed=request.seed,
        )


def _component(pipeline: object, name: str) -> object:
    """A pipeline component, whether it hangs off the pipeline or its components."""
    direct = getattr(pipeline, name, None)
    if direct is not None:
        return direct

    components = getattr(pipeline, "components", None)
    if isinstance(components, dict):
        return components[name]
    return getattr(components, name)


def _named(results: object) -> tuple:
    """The named outputs, however the pipeline hands them back."""
    if isinstance(results, dict):
        return results["videos"], results["audio"], results["sampling_rate"]
    if hasattr(results, "videos"):
        return results.videos, results.audio, results.sampling_rate

    return tuple(results)
runware.yaml
configVersion: 1
id: minimax-h3-turbo
name: MiniMax H3 Turbo
source:
  type: code
  entry: model.py
compute:
  gpuType: rtx-pro-6000
build:
  requirements:
    - torch==2.14.1
    - torchvision==0.29.1
    - diffusers==0.42.1
    - transformers==5.21.0
    - accelerate==1.15.0
    - av==16.0.1
    - torchao==0.18.0
    - peft==0.21.3
volumes:
  - /weights

Deploying

Deploy it as it is, or take the files above and deploy your own copy. Nothing you change reaches back to this page.

minimax-h3-turbortx-pro-6000source
From a URL
runware serverless deploy --from https://runware.ai/docs/serverless/examples/minimax-h3-turbo.zip
From a clone
runware serverless deploy model.py \
  --id minimax-h3-turbo \
  --gpu-type rtx-pro-6000 \
  --requirement torch==2.14.1 \
  --requirement torchvision==0.29.1 \
  --requirement diffusers==0.42.1 \
  --requirement transformers==5.21.0 \
  --requirement accelerate==1.15.0 \
  --requirement av==16.0.1 \
  --requirement torchao==0.18.0 \
  --requirement peft==0.21.3 \
  --volume /weights

Calling it

One request that works, against the app you just deployed. The fields are the ones the entry declares above, and anything it does not declare is refused rather than ignored.

import { createClient } from '@runware/sdk'

const client = await createClient({ apiKey: process.env.RUNWARE_API_KEY })

const task = await client.invoke({
  appId: 'minimax-h3-turbo',
  endpointPath: 'predict',
  payload: {
    request: {
      prompt: 'A paper boat drifting down a rain gutter, close up'
    }
  }
})
import asyncio
import os

from runware import Runware


async def main():
    client = Runware(api_key=os.environ["RUNWARE_API_KEY"])
    try:
        task = await client.invoke(
            "minimax-h3-turbo",
            "predict",
            {
                "request": {
                    "prompt": "A paper boat drifting down a rain gutter, close up"
                }
            },
        )
    finally:
        await client.close()


asyncio.run(main())
curl https://api.serverless.runware.ai/v1/apps/minimax-h3-turbo/invoke-async/predict \
  -H "Authorization: Bearer $RUNWARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taskId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "payload": {
      "request": {
        "prompt": "A paper boat drifting down a rain gutter, close up"
      }
    }
  }'
cat <<'EOF' | runware serverless apps invoke minimax-h3-turbo predict -f -
{
  "request": {
    "prompt": "A paper boat drifting down a rain gutter, close up"
  }
}
EOF
{
  "taskId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "payload": {
    "request": {
      "prompt": "A paper boat drifting down a rain gutter, close up"
    }
  }
}

What it costs

This entry is pinned to rtx-pro-6000, which is the card it was tested on rather than the only one it runs on: --gpu-typedeploys it somewhere else. You pay for that card by the second while a worker holds it, and for nothing else. Pricing covers what meters, and the rates are published per GPU-second.