MiniMax H3 Image
MiniMax's image model, six steps and no classifier-free guidance, at four megapixels or at the sixteen MiniMax recommends. Your prompt is read verbatim with no chat template, so a long and complete description is what it works best from, and the first 4096 tokens are what it reads. Strongest at photography, dense scenes and rendered text.
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.
"""MiniMax H3 Image, generated from a declarative template."""
from __future__ import annotations
import base64
import io
from typing import Literal
from pydantic import BaseModel, ConfigDict, Field
from runware_serverless import serve
MODEL = "MiniMaxAI/MiniMax-H3-Image"
REVISION = "492fd8c4eca666f1085f57e30738c1e0d86b3439"
CACHE = "/weights"
SIZES = {
"1:1": (4096, 4096),
"4:3": (4736, 3552),
"3:4": (3552, 4736),
"3:2": (5024, 3360),
"2:3": (3360, 5024),
"16:9": (5472, 3072),
"9:16": (3072, 5472),
"21:9": (6272, 2688),
}
"""The sizes MiniMax recommends, which are the ones the model was tuned at. They
are all about 16.8 megapixels, so one of them costs what another does."""
def canvas(aspect: str, megapixels: int) -> tuple[int, int]:
"""The size to generate, which is a recommended one or that one halved.
Halving keeps the ratio exactly and lands just over four megapixels, and four
is the area the model generates at whatever it is asked for, so this is the
cheap end rather than a small image.
"""
width, height = SIZES[aspect]
if megapixels == 16:
return width, height
return width // 2, height // 2
# The heaviest request there is, so a cold start that succeeds cannot run out of
# card on somebody's first 16-megapixel call.
WARMUP = SIZES["1:1"]
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, read verbatim with no chat template. A long, complete description"
" works best, and the model reads the first 4096 tokens of it."
),
)
aspect: Literal["1:1", "4:3", "3:4", "3:2", "2:3", "16:9", "9:16", "21:9"] = Field(
default="1:1",
description="The shape of the image, from the ratios MiniMax recommends.",
)
megapixels: Literal[4, 16] = Field(
default=4,
description=(
"How large to generate. 4 is the floor and there is nothing cheaper: the model"
" generates on a canvas of four megapixels whatever it is asked for, so a smaller"
" request costs the same and returns less. 16 is the size MiniMax recommends and"
" four times the work."
),
)
seed: int | None = Field(default=None, description="Repeat a result by repeating its seed.")
# No step count and no guidance. The checkpoint is distilled twice over: the
# transformer carries one output head per step, so six is the schedule its
# weights were built around rather than a number to pass, and guidance is in
# the weights too, so there is no scale and no negative prompt either.
class Generated(BaseModel):
# JPEG and not PNG, which is what most image entries here return. At the
# larger scale a result is about 16.8 megapixels, where a PNG runs to tens of
# megabytes, and this is a response body rather than a file on disk.
image: str = Field(description="The result as a base64 JPEG.")
width: int
height: int
aspect: str
seed: int | None
@serve
class GeneratedImage:
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
# Two calls rather than one. from_pretrained builds the pipeline without
# reading any weights, and load_components is what fetches them, so a
# failure to resolve the repository and a failure to load it are
# separate and report separately.
self.pipeline = ModularPipeline.from_pretrained(
MODEL, revision=REVISION, cache_dir=CACHE
)
from diffusers import MiniMaxH3ImageTransformer2DModel, TorchAoConfig
from transformers import Qwen3VLForConditionalGeneration
from transformers import TorchAoConfig as TransformersTorchAoConfig
from torchao.quantization import Float8DynamicActivationFloat8WeightConfig
self.pipeline.update_components(
transformer=MiniMaxH3ImageTransformer2DModel.from_pretrained(
MODEL,
subfolder="transformer_diffusers",
revision=REVISION,
cache_dir=CACHE,
dtype=torch.bfloat16,
device_map="cuda",
quantization_config=TorchAoConfig(
Float8DynamicActivationFloat8WeightConfig(),
modules_to_not_convert=[
"proj_in",
"context_embedder",
"time_proj",
"time_embedder",
"token_refiner",
"norm_out",
"pdd_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(
Float8DynamicActivationFloat8WeightConfig(),
modules_to_not_convert=[
"model.visual",
"model.language_model.embed_tokens",
"model.language_model.norm",
"lm_head",
],
),
),
)
# Every component lands on the card as it loads. Host RAM is half the
# card's VRAM, so a pipeline assembled on the host and moved has a
# ceiling well below the card's, and the kill arrives as the container's
# exit 137 rather than as a CUDA error.
self.pipeline.load_components(dtype=torch.bfloat16, device_map="cuda")
# At the largest of the offered sizes, so the readiness check is what
# finds out whether the card holds the peak, rather than somebody's
# first call. A cheaper warmup would not: the canvas has a
# four-megapixel floor, so a small one exercises a path no request takes.
self.pipeline(
prompt="warmup",
width=WARMUP[0],
height=WARMUP[1],
output="images",
)
def predict(self, request: Request) -> Generated:
generator = None
if request.seed is not None:
# On the host and not the card, which is what the model card asks
# for: the noise its results were produced against is drawn there.
generator = self.torch.Generator().manual_seed(request.seed)
width, height = canvas(request.aspect, request.megapixels)
# A modular pipeline returns its whole state and you name what you want
# out of it, rather than an object with an images attribute.
image = self.pipeline(
prompt=request.prompt,
width=width,
height=height,
generator=generator,
output="images",
)[0]
buffer = io.BytesIO()
image.save(buffer, format="JPEG", quality=95)
return Generated(
image=base64.b64encode(buffer.getvalue()).decode("ascii"),
width=width,
height=height,
aspect=request.aspect,
seed=request.seed,
)configVersion: 1
id: minimax-h3-image
name: MiniMax H3 Image
source:
type: code
entry: model.py
compute:
gpuType: rtx-pro-6000
build:
requirements:
- torch==2.14.1
- torchvision==0.29.1
- diffusers @
git+https://github.com/huggingface/diffusers@529403c21a36d03551f09bfd4d432cb64ab6d450
- transformers==5.21.0
- accelerate==1.15.0
- torchao==0.18.0
- pillow==13.0.0
baseImage: python:3.12
volumes:
- /weightsDeploying
Deploy it as it is, or take the files above and deploy your own copy. Nothing you change reaches back to this page.
runware serverless deploy --from https://runware.ai/docs/serverless/examples/minimax-h3-image.ziprunware serverless deploy model.py \
--id minimax-h3-image \
--gpu-type rtx-pro-6000 \
--base-image python:3.12 \
--requirement torch==2.14.1 \
--requirement torchvision==0.29.1 \
--requirement diffusers @ git+https://github.com/huggingface/diffusers@529403c21a36d03551f09bfd4d432cb64ab6d450 \
--requirement transformers==5.21.0 \
--requirement accelerate==1.15.0 \
--requirement torchao==0.18.0 \
--requirement pillow==13.0.0 \
--volume /weightsCalling 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-image',
endpointPath: 'predict',
payload: {
request: {
prompt: 'An overhead photograph of a rustic farm-to-table spread on a weathered wooden table: a round loaf of sourdough on burlap, wedges of cheese on a dark board, a copper bowl of vegetables, vine tomatoes, olives and walnuts.'
}
}
})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-image",
"predict",
{
"request": {
"prompt": "An overhead photograph of a rustic farm-to-table spread on a weathered wooden table: a round loaf of sourdough on burlap, wedges of cheese on a dark board, a copper bowl of vegetables, vine tomatoes, olives and walnuts."
}
},
)
finally:
await client.close()
asyncio.run(main())curl https://api.serverless.runware.ai/v1/apps/minimax-h3-image/invoke-async/predict \
-H "Authorization: Bearer $RUNWARE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"taskId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"payload": {
"request": {
"prompt": "An overhead photograph of a rustic farm-to-table spread on a weathered wooden table: a round loaf of sourdough on burlap, wedges of cheese on a dark board, a copper bowl of vegetables, vine tomatoes, olives and walnuts."
}
}
}'cat <<'EOF' | runware serverless apps invoke minimax-h3-image predict -f -
{
"request": {
"prompt": "An overhead photograph of a rustic farm-to-table spread on a weathered wooden table: a round loaf of sourdough on burlap, wedges of cheese on a dark board, a copper bowl of vegetables, vine tomatoes, olives and walnuts."
}
}
EOF{
"taskId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"payload": {
"request": {
"prompt": "An overhead photograph of a rustic farm-to-table spread on a weathered wooden table: a round loaf of sourdough on burlap, wedges of cheese on a dark board, a copper bowl of vegetables, vine tomatoes, olives and walnuts."
}
}
}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.