Instructions to use MiniMaxAI/MiniMax-H3-Image-PE with libraries, inference providers, notebooks, and local apps. Follow these links to get started.

Libraries

How to use MiniMaxAI/MiniMax-H3-Image-PE with Transformers:

# Use a pipeline as a high-level helper
from transformers import pipeline

pipe = pipeline("text-generation", model="MiniMaxAI/MiniMax-H3-Image-PE")
messages = [
    {
        "role": "user",
        "content": [
            {"type": "image", "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/p-blog/candy.JPG"},
            {"type": "text", "text": "What animal is on the candy?"}
        ]
    },
]
pipe(text=messages)

# pip install -U transformers accelerate
# Load model directly
from transformers import AutoProcessor, AutoModelForMultimodalLM

processor = AutoProcessor.from_pretrained("MiniMaxAI/MiniMax-H3-Image-PE")
model = AutoModelForMultimodalLM.from_pretrained("MiniMaxAI/MiniMax-H3-Image-PE", device_map="auto")
messages = [
    {
        "role": "user",
        "content": [
            {"type": "image", "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/p-blog/candy.JPG"},
            {"type": "text", "text": "What animal is on the candy?"}
        ]
    },
]
inputs = processor.apply_chat_template(
	messages,
	add_generation_prompt=True,
	tokenize=True,
	return_dict=True,
	return_tensors="pt",
).to(model.device)

outputs = model.generate(**inputs, max_new_tokens=256)
print(processor.decode(outputs[0][inputs["input_ids"].shape[-1]:]))

Notebooks
Google Colab
Kaggle
Local Apps Settings

vLLM

How to use MiniMaxAI/MiniMax-H3-Image-PE with vLLM:

Install from pip and serve model

# Install vLLM from pip:
pip install vllm
# Start the vLLM server:
vllm serve "MiniMaxAI/MiniMax-H3-Image-PE"
# Call the server using curl (OpenAI-compatible API):
curl -X POST "http://localhost:8000/v1/chat/completions" \
	-H "Content-Type: application/json" \
	--data '{
		"model": "MiniMaxAI/MiniMax-H3-Image-PE",
		"messages": [
			{
				"role": "user",
				"content": "What is the capital of France?"
			}
		]
	}'

Use Docker

docker model run hf.co/MiniMaxAI/MiniMax-H3-Image-PE

SGLang

How to use MiniMaxAI/MiniMax-H3-Image-PE with SGLang:

Install from pip and serve model

# Install SGLang from pip:
pip install sglang
# Start the SGLang server:
python3 -m sglang.launch_server \
    --model-path "MiniMaxAI/MiniMax-H3-Image-PE" \
    --host 0.0.0.0 \
    --port 30000
# Call the server using curl (OpenAI-compatible API):
curl -X POST "http://localhost:30000/v1/chat/completions" \
	-H "Content-Type: application/json" \
	--data '{
		"model": "MiniMaxAI/MiniMax-H3-Image-PE",
		"messages": [
			{
				"role": "user",
				"content": "What is the capital of France?"
			}
		]
	}'

Use Docker images

docker run --gpus all \
    --shm-size 32g \
    -p 30000:30000 \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    --env "HF_TOKEN=<secret>" \
    --ipc=host \
    lmsysorg/sglang:latest \
    python3 -m sglang.launch_server \
        --model-path "MiniMaxAI/MiniMax-H3-Image-PE" \
        --host 0.0.0.0 \
        --port 30000
# Call the server using curl (OpenAI-compatible API):
curl -X POST "http://localhost:30000/v1/chat/completions" \
	-H "Content-Type: application/json" \
	--data '{
		"model": "MiniMaxAI/MiniMax-H3-Image-PE",
		"messages": [
			{
				"role": "user",
				"content": "What is the capital of France?"
			}
		]
	}'

Docker Model Runner
How to use MiniMaxAI/MiniMax-H3-Image-PE with Docker Model Runner:
```
docker model run hf.co/MiniMaxAI/MiniMax-H3-Image-PE
```

MiniMax-H3-Image-PE / README.md

multimodalart HF Staff

Add a Diffusers usage section (Modular Diffusers custom blocks)

2565309 about 7 hours ago

preview code

Raw History Blame

13.2 kB

---
pipeline_tag: text-generation
license: other
license_name: minimax-h3-image-community-license-agreement
license_link: https://huggingface.co/MiniMaxAI/MiniMax-H3-Image/blob/main/LICENSE
library_name: transformers
language:
- en
tags:
- prompt-expansion
- text-to-image
- minimax-h3
- fp4
- sglang
base_model:
- Qwen/Qwen3.8-27B
---
<div align="center">
  <img width="100%" src="assets/minimax-h3-image.jpg" alt="MiniMax H3 image, Open Weights">
</div>

<p align="center">
  <a href="https://hailuoai.video" target="_blank"><img src="https://img.shields.io/badge/Hailuo%20AI-FF6C37?logo=minimax&logoColor=white" alt="Hailuo AI"></a>
  <a href="https://platform.minimax.io" target="_blank"><img src="https://img.shields.io/badge/API-FF6C37?logo=minimax&logoColor=white" alt="API"></a>
  <a href="https://www.minimax.io" target="_blank"><img src="https://img.shields.io/badge/MiniMax%20Website-FF6C37?logo=minimax&logoColor=white" alt="MiniMax Website"></a>
  <a href="https://github.com/MiniMax-AI/MiniMax-H3" target="_blank"><img src="https://img.shields.io/badge/GitHub-181717?logo=github&logoColor=white" alt="GitHub"></a>
  <a href="https://huggingface.co/MiniMaxAI/MiniMax-H3-Image-PE" target="_blank"><img src="https://img.shields.io/badge/Hugging%20Face-FFD21E?logo=huggingface&logoColor=black" alt="Hugging Face"></a>
  <br>
  <a href="https://modelscope.cn/organization/minimax" target="_blank" rel="noopener noreferrer"><img alt="ModelScope MiniMax AI" src="https://img.shields.io/badge/ModelScope-MiniMax%20AI-white?labelColor=%23EF3D5D"></a>
  <a href="https://platform.minimaxi.com/docs/faq/contact-us" target="_blank"><img src="https://img.shields.io/badge/WeChat-07C160?logo=wechat&logoColor=white" alt="WeChat"></a>
  <a href="https://discord.com/invite/dbMxutw7tP" target="_blank"><img src="https://img.shields.io/badge/Discord-5865F2?logo=discord&logoColor=white" alt="Discord"></a>
  <a href="https://huggingface.co/MiniMaxAI/MiniMax-H3-Image/blob/main/LICENSE"><img src="https://img.shields.io/badge/LICENSE-4CAF50?logo=creativecommons&logoColor=white" alt="LICENSE"></a>
</p>

# MiniMax-H3-Image-PE

## Online API

Use MiniMax-H3-Image directly via API.

- Global: [platform.minimax.io](https://platform.minimax.io/docs/guides/image-generation) | CN: [platform.minimax.cn](https://platform.minimax.cn/docs/guides/image-generation)

API docs:
- Text-to-image: [EN-docs](https://platform.minimax.io/docs/api-reference/image-generation-h3-generations), [CN-docs](https://platform.minimax.cn/docs/api-reference/image-generation-h3-generations)
- Image editing: [EN-docs](https://platform.minimax.io/docs/api-reference/image-generation-h3-edits), [CN-docs](https://platform.minimax.cn/docs/api-reference/image-generation-h3-edits)
- Prompt expansion: [EN-docs](https://platform.minimax.io/docs/api-reference/image-generation-h3-context-ir), [CN-docs](https://platform.minimax.cn/docs/api-reference/image-generation-h3-context-ir)

## Introduction

MiniMax-H3-Image-PE provides prompt expansion (PE) for
[MiniMax-H3-Image](https://huggingface.co/MiniMaxAI/MiniMax-H3-Image).
It turns a short request into a detailed description of the intended image,
together with an aspect-ratio recommendation for image generation.

This repository covers two workflows:

| Workflow | Input | Released assets |
| --- | --- | --- |
| **Text-to-image (T2I) PE** | A text instruction | MiniMax-H3-Image-PE weights (fine-tuned from [Qwen3.8-27B](https://huggingface.co/Qwen/Qwen3.8-27B), FP4), task and system prompts, and a client example |
| **Image editing PE** | An editing instruction and reference images | A task prompt and message-assembly example for a vision-language model of your choice. **Image editing PE is still under development; this release provides its prompt only.** |

The examples below explain how to use MiniMax-H3-Image-PE and the image editing task prompt.

## How to use T2I PE

Run the examples from a local copy of this repository so the relative prompt and
script paths resolve correctly.

### Serve MiniMax-H3-Image-PE

We recommend SGLang with `sglang>=0.5.23` and `xgrammar>=0.2.7`.

```bash
sglang serve \
  --model-path MiniMaxAI/MiniMax-H3-Image-PE \
  --served-model-name MiniMax-H3-Image-PE \
  --model-type llm \
  --reasoning-parser qwen3 \
  --grammar-backend xgrammar \
  --constrained-json-disable-any-whitespace \
  --host 0.0.0.0 \
  --port 30000
```

SGLang reads the FP4 configuration from the checkpoint. XGrammar constrains the
answer to the JSON schema, and the reasoning parser separates reasoning from the
final answer.

### Expand a prompt

Load the task prompt and insert your instruction with `.format(user_query)`:

```python
from pathlib import Path
task_prompt = Path("prompt/t2i/task_prompt.txt").read_text(encoding="utf-8")
user_query = "An orange tabby cat sleeping on a sunlit windowsill."
user_prompt = task_prompt.format(user_query)
```

Send it with the system prompt and request parameters:

```python
import json
from urllib.request import Request, urlopen
system_prompt = Path("prompt/t2i/system_prompt.txt").read_text(encoding="utf-8").strip()
params = json.loads(Path("prompt/t2i/request_params.json").read_text(encoding="utf-8"))
payload = {
    **params,
    "model": "MiniMax-H3-Image-PE",
    "messages": [
        {"role": "system", "content": system_prompt},
        {"role": "user", "content": user_prompt},
    ],
    "stream": False,
}
request = Request(
    "http://0.0.0.0:30000/v1/chat/completions",
    data=json.dumps(payload).encode("utf-8"),
    headers={"Content-Type": "application/json"},
)
with urlopen(request, timeout=1200) as response:
    result = json.load(response)
pe_result = json.loads(result["choices"][0]["message"]["content"])
print(pe_result)
```

The included client performs the same request and checks the response:

```bash
python3 scripts/expand_prompt.py \
  --url http://0.0.0.0:30000 \
  --model MiniMax-H3-Image-PE \
  "An orange tabby cat sleeping on a sunlit windowsill."
```

### Request parameters

The examples load the defaults from
[`prompt/t2i/request_params.json`](prompt/t2i/request_params.json):

| Parameter | Value |
| --- | --- |
| `temperature` / `top_p` / `top_k` | 1.0 / 0.95 / 20 |
| `min_p` | 0.0 |
| `presence_penalty` / `repetition_penalty` | 0.0 / 1.0 |
| `max_tokens` | 4096, including thinking and the final answer |
| `reasoning_effort` | `xhigh` |
| `enable_thinking` / `preserve_thinking` | `true` / `true` |
| `response_format` | JSON schema for `expanded_caption` and `aspect_ratio` |

### Output

With `--reasoning-parser qwen3`, `message.content` contains the JSON answer.
Reasoning is returned separately in `message.reasoning_content`. Example output:

```json
{
  "expanded_caption": "A warm photograph shows an orange tabby cat sleeping on a sunlit windowsill, with soft afternoon light falling across its fur.",
  "aspect_ratio": "3:2"
}
```

When your aspect-ratio selection is `auto`, use the `aspect_ratio` returned by the
model for image generation. If you select an explicit ratio, use your selected
ratio instead of the model's recommendation at the image-generation stage.

## How to use Image editing PE

Use the task prompt with a vision-language model that supports interleaved text
and images. The example below describes message assembly without selecting a
model or making an API call.

### Inputs

Provide the following inputs:

| Input | Description |
| --- | --- |
| `user_query` | The editing instruction. Refer to images in their supplied order. |
| `references` | At least one prepared image, in order, with its original display aspect ratio as a reduced `W:H` string. Use `None` when the source ratio is unknown. |
| `aspect_ratio` | The target ratio: `adaptive` to let the model choose, or an explicit positive-integer `W:H` string. |

### Assemble the message

Load [`prompt/edit/task_prompt.txt`](prompt/edit/task_prompt.txt) unchanged as the
first content part. Follow it with the image count, each image's label and source
ratio immediately before that image, and your editing instruction and target ratio
in the final text part. This produces one user message.

The fixed task prompt forms a shared prefix across requests, allowing reuse by
services that support prefix caching. Cache behavior depends on the provider.

In the pseudocode below, `source_image` and `reference_image` are already prepared
image inputs. The text and image parts are conceptual; adapt their representation
to your model's interface.

```python
import json
from pathlib import Path
task_prompt = Path("prompt/edit/task_prompt.txt").read_text(encoding="utf-8")
user_query = "Replace the bag in the first image with the bag in the second image."
aspect_ratio = "adaptive"  # Or an explicit ratio, such as "16:9".
references = [
    {"image": source_image, "aspect_ratio": "3:2"},
    {"image": reference_image, "aspect_ratio": "1:1"},
]
count = len(references)
content = [
    {"type": "text", "text": task_prompt},
    {"type": "text", "text": (
        f"Reference Image Count:\n"
        f"{count} input image(s), labeled <Picture 1> through <Picture {count}>."
    )},
]
for index, reference in enumerate(references, start=1):
    metadata = "aspect_ratio unavailable"
    if reference["aspect_ratio"] is not None:
        metadata = f"aspect_ratio {reference['aspect_ratio']}"
    content.extend([
        {"type": "text", "text": f"Reference Media:\n- <Picture {index}> [{metadata}]"},
        {"type": "image", "image": reference["image"]},
    ])
user_input = (
    "\nUser Editing Instruction (JSON string):\n"
    f"{json.dumps(user_query, ensure_ascii=False)}\n\n"
    f"User Aspect Ratio Selection:\n{aspect_ratio}\n\n"
    "Apply the instructions above to the supplied inputs and reference images. "
    "Output only the required two-field JSON object."
)
content.append({"type": "text", "text": user_input})
messages = [{"role": "user", "content": content}]
```

### Output

```json
{
  "expanded_caption": "<one paragraph describing the intended edit>",
  "target_aspect_ratio": "3:2"
}
```

The description identifies source subjects, states what is preserved or changed,
and describes new content. Descriptive prose is English; literal text retains the
language you request. `target_aspect_ratio` is a positive-integer `W:H` string.
If you select an explicit ratio, the model preserves it exactly. If you select
`adaptive`, the model determines a numeric ratio for the intended edited image.

## Use with Diffusers

MiniMax-H3-Image-PE can also run locally in Transformers through the
[`diffusers/minimax-h3-image-pe-blocks`](https://huggingface.co/diffusers/minimax-h3-image-pe-blocks)
Modular Diffusers blocks. The blocks use the released prompts and request
parameters for T2I PE and Image editing PE, and XGrammar constrains the answer
to the JSON schema.

### Load MiniMax-H3-Image-PE

```bash
pip install -U diffusers transformers xgrammar bitsandbytes kernels flash-linear-attention
```

```python
import torch
from diffusers import ModularPipeline
pe = ModularPipeline.from_pretrained("diffusers/minimax-h3-image-pe-blocks", trust_remote_code=True)
pe.load_components(dtype=torch.bfloat16, device_map="cuda")
```

The FP4 weights stay in 4-bit and use about 19 GiB of GPU memory. GPUs with
native FP4 support run the NVFP4 weights directly; other GPUs use bitsandbytes
FP4.

### Expand a prompt

Pass a request to run T2I PE:

```python
state = pe(prompt="An orange tabby cat sleeping on a sunlit windowsill.")
print(state.get("prompt"), state.get("aspect_ratio"))
```

Pass reference images to run Image editing PE. Refer to the images in their
supplied order:

```python
state = pe(
    prompt="Replace the bag in the first image with the bag in the second image.",
    image=["source.png", "bag.png"],
    aspect_ratio="adaptive",
)
print(state.get("prompt"), state.get("aspect_ratio"))
```

### Inputs and outputs

| Name | Description |
| --- | --- |
| `prompt` | Input: the request or editing instruction. Output: the expanded caption. |
| `image` | One or more reference images (PIL images, paths or URLs). Selects Image editing PE. |
| `aspect_ratio` | Input, Image editing PE only: `adaptive` or an explicit `W:H` ratio. Output: the target ratio. |
| `enable_thinking` | Reasoning before the answer, `True` by default as in the released request. |
| `max_new_tokens` | Token budget, including thinking and the final answer. |
| `seed` | Seed for a reproducible expansion. |
| `reasoning` | Output: the model's reasoning. |

Activations run in bf16, so outputs are not identical to the SGLang deployment
above.

## License

- MiniMax-H3-Image-PE is part of MiniMax-H3-Image and is released under the [MiniMax-H3-Image Community License Agreement](https://huggingface.co/MiniMaxAI/MiniMax-H3-Image/blob/main/LICENSE).
- MiniMax-H3-Image-PE is derived from [Qwen3.8-27B](https://huggingface.co/Qwen/Qwen3.8-27B), which is licensed under the Apache 2.0 License.
- The separate written authorization described in Section IV of the license is requested through [platform.minimax.io/license](https://platform.minimax.io/license).

## Contact Us

Contact us at [model@minimax.io](mailto:model@minimax.io).

	---
	pipeline_tag: text-generation
	license: other
	license_name: minimax-h3-image-community-license-agreement
	license_link: https://huggingface.co/MiniMaxAI/MiniMax-H3-Image/blob/main/LICENSE
	library_name: transformers
	language:
	- en
	tags:
	- prompt-expansion
	- text-to-image
	- minimax-h3
	- fp4
	- sglang
	base_model:
	- Qwen/Qwen3.8-27B
	---

	<div align="center">
	<img width="100%" src="assets/minimax-h3-image.jpg" alt="MiniMax H3 image, Open Weights">
	</div>

	<p align="center">
	<a href="https://hailuoai.video" target="_blank"><img src="https://img.shields.io/badge/Hailuo%20AI-FF6C37?logo=minimax&logoColor=white" alt="Hailuo AI"></a>
	<a href="https://platform.minimax.io" target="_blank"><img src="https://img.shields.io/badge/API-FF6C37?logo=minimax&logoColor=white" alt="API"></a>
	<a href="https://www.minimax.io" target="_blank"><img src="https://img.shields.io/badge/MiniMax%20Website-FF6C37?logo=minimax&logoColor=white" alt="MiniMax Website"></a>
	<a href="https://github.com/MiniMax-AI/MiniMax-H3" target="_blank"><img src="https://img.shields.io/badge/GitHub-181717?logo=github&logoColor=white" alt="GitHub"></a>
	<a href="https://huggingface.co/MiniMaxAI/MiniMax-H3-Image-PE" target="_blank"><img src="https://img.shields.io/badge/Hugging%20Face-FFD21E?logo=huggingface&logoColor=black" alt="Hugging Face"></a>
	<br>
	<a href="https://modelscope.cn/organization/minimax" target="_blank" rel="noopener noreferrer"><img alt="ModelScope MiniMax AI" src="https://img.shields.io/badge/ModelScope-MiniMax%20AI-white?labelColor=%23EF3D5D"></a>
	<a href="https://platform.minimaxi.com/docs/faq/contact-us" target="_blank"><img src="https://img.shields.io/badge/WeChat-07C160?logo=wechat&logoColor=white" alt="WeChat"></a>
	<a href="https://discord.com/invite/dbMxutw7tP" target="_blank"><img src="https://img.shields.io/badge/Discord-5865F2?logo=discord&logoColor=white" alt="Discord"></a>
	<a href="https://huggingface.co/MiniMaxAI/MiniMax-H3-Image/blob/main/LICENSE"><img src="https://img.shields.io/badge/LICENSE-4CAF50?logo=creativecommons&logoColor=white" alt="LICENSE"></a>
	</p>

	# MiniMax-H3-Image-PE

	## Online API

	Use MiniMax-H3-Image directly via API.

	- Global: [platform.minimax.io](https://platform.minimax.io/docs/guides/image-generation) \| CN: [platform.minimax.cn](https://platform.minimax.cn/docs/guides/image-generation)

	API docs:
	- Text-to-image: [EN-docs](https://platform.minimax.io/docs/api-reference/image-generation-h3-generations), [CN-docs](https://platform.minimax.cn/docs/api-reference/image-generation-h3-generations)
	- Image editing: [EN-docs](https://platform.minimax.io/docs/api-reference/image-generation-h3-edits), [CN-docs](https://platform.minimax.cn/docs/api-reference/image-generation-h3-edits)
	- Prompt expansion: [EN-docs](https://platform.minimax.io/docs/api-reference/image-generation-h3-context-ir), [CN-docs](https://platform.minimax.cn/docs/api-reference/image-generation-h3-context-ir)

	## Introduction

	MiniMax-H3-Image-PE provides prompt expansion (PE) for
	[MiniMax-H3-Image](https://huggingface.co/MiniMaxAI/MiniMax-H3-Image).
	It turns a short request into a detailed description of the intended image,
	together with an aspect-ratio recommendation for image generation.

	This repository covers two workflows:

	\| Workflow \| Input \| Released assets \|
	\| --- \| --- \| --- \|
	\| Text-to-image (T2I) PE \| A text instruction \| MiniMax-H3-Image-PE weights (fine-tuned from [Qwen3.8-27B](https://huggingface.co/Qwen/Qwen3.8-27B), FP4), task and system prompts, and a client example \|
	\| Image editing PE \| An editing instruction and reference images \| A task prompt and message-assembly example for a vision-language model of your choice. Image editing PE is still under development; this release provides its prompt only. \|

	The examples below explain how to use MiniMax-H3-Image-PE and the image editing task prompt.

	## How to use T2I PE

	Run the examples from a local copy of this repository so the relative prompt and
	script paths resolve correctly.

	### Serve MiniMax-H3-Image-PE

	We recommend SGLang with `sglang>=0.5.23` and `xgrammar>=0.2.7`.

	```bash
	sglang serve \
	--model-path MiniMaxAI/MiniMax-H3-Image-PE \
	--served-model-name MiniMax-H3-Image-PE \
	--model-type llm \
	--reasoning-parser qwen3 \
	--grammar-backend xgrammar \
	--constrained-json-disable-any-whitespace \
	--host 0.0.0.0 \
	--port 30000
	```

	SGLang reads the FP4 configuration from the checkpoint. XGrammar constrains the
	answer to the JSON schema, and the reasoning parser separates reasoning from the
	final answer.

	### Expand a prompt

	Load the task prompt and insert your instruction with `.format(user_query)`:

	```python
	from pathlib import Path

	task_prompt = Path("prompt/t2i/task_prompt.txt").read_text(encoding="utf-8")
	user_query = "An orange tabby cat sleeping on a sunlit windowsill."
	user_prompt = task_prompt.format(user_query)
	```

	Send it with the system prompt and request parameters:

	```python
	import json
	from urllib.request import Request, urlopen

	system_prompt = Path("prompt/t2i/system_prompt.txt").read_text(encoding="utf-8").strip()
	params = json.loads(Path("prompt/t2i/request_params.json").read_text(encoding="utf-8"))
	payload = {
	**params,
	"model": "MiniMax-H3-Image-PE",
	"messages": [
	{"role": "system", "content": system_prompt},
	{"role": "user", "content": user_prompt},
	],
	"stream": False,
	}
	request = Request(
	"http://0.0.0.0:30000/v1/chat/completions",
	data=json.dumps(payload).encode("utf-8"),
	headers={"Content-Type": "application/json"},
	)
	with urlopen(request, timeout=1200) as response:
	result = json.load(response)
	pe_result = json.loads(result["choices"][0]["message"]["content"])
	print(pe_result)
	```

	The included client performs the same request and checks the response:

	```bash
	python3 scripts/expand_prompt.py \
	--url http://0.0.0.0:30000 \
	--model MiniMax-H3-Image-PE \
	"An orange tabby cat sleeping on a sunlit windowsill."
	```

	### Request parameters

	The examples load the defaults from
	[`prompt/t2i/request_params.json`](prompt/t2i/request_params.json):

	\| Parameter \| Value \|
	\| --- \| --- \|
	\| `temperature` / `top_p` / `top_k` \| 1.0 / 0.95 / 20 \|
	\| `min_p` \| 0.0 \|
	\| `presence_penalty` / `repetition_penalty` \| 0.0 / 1.0 \|
	\| `max_tokens` \| 4096, including thinking and the final answer \|
	\| `reasoning_effort` \| `xhigh` \|
	\| `enable_thinking` / `preserve_thinking` \| `true` / `true` \|
	\| `response_format` \| JSON schema for `expanded_caption` and `aspect_ratio` \|

	### Output

	With `--reasoning-parser qwen3`, `message.content` contains the JSON answer.
	Reasoning is returned separately in `message.reasoning_content`. Example output:

	```json
	{
	"expanded_caption": "A warm photograph shows an orange tabby cat sleeping on a sunlit windowsill, with soft afternoon light falling across its fur.",
	"aspect_ratio": "3:2"
	}
	```

	When your aspect-ratio selection is `auto`, use the `aspect_ratio` returned by the
	model for image generation. If you select an explicit ratio, use your selected
	ratio instead of the model's recommendation at the image-generation stage.

	## How to use Image editing PE

	Use the task prompt with a vision-language model that supports interleaved text
	and images. The example below describes message assembly without selecting a
	model or making an API call.

	### Inputs

	Provide the following inputs:

	\| Input \| Description \|
	\| --- \| --- \|
	\| `user_query` \| The editing instruction. Refer to images in their supplied order. \|
	\| `references` \| At least one prepared image, in order, with its original display aspect ratio as a reduced `W:H` string. Use `None` when the source ratio is unknown. \|
	\| `aspect_ratio` \| The target ratio: `adaptive` to let the model choose, or an explicit positive-integer `W:H` string. \|

	### Assemble the message

	Load [`prompt/edit/task_prompt.txt`](prompt/edit/task_prompt.txt) unchanged as the
	first content part. Follow it with the image count, each image's label and source
	ratio immediately before that image, and your editing instruction and target ratio
	in the final text part. This produces one user message.

	The fixed task prompt forms a shared prefix across requests, allowing reuse by
	services that support prefix caching. Cache behavior depends on the provider.

	In the pseudocode below, `source_image` and `reference_image` are already prepared
	image inputs. The text and image parts are conceptual; adapt their representation
	to your model's interface.

	```python
	import json
	from pathlib import Path

	task_prompt = Path("prompt/edit/task_prompt.txt").read_text(encoding="utf-8")
	user_query = "Replace the bag in the first image with the bag in the second image."
	aspect_ratio = "adaptive" # Or an explicit ratio, such as "16:9".
	references = [
	{"image": source_image, "aspect_ratio": "3:2"},
	{"image": reference_image, "aspect_ratio": "1:1"},
	]

	count = len(references)
	content = [
	{"type": "text", "text": task_prompt},
	{"type": "text", "text": (
	f"Reference Image Count:\n"
	f"{count} input image(s), labeled <Picture 1> through <Picture {count}>."
	)},
	]
	for index, reference in enumerate(references, start=1):
	metadata = "aspect_ratio unavailable"
	if reference["aspect_ratio"] is not None:
	metadata = f"aspect_ratio {reference['aspect_ratio']}"
	content.extend([
	{"type": "text", "text": f"Reference Media:\n- <Picture {index}> [{metadata}]"},
	{"type": "image", "image": reference["image"]},
	])

	user_input = (
	"\nUser Editing Instruction (JSON string):\n"
	f"{json.dumps(user_query, ensure_ascii=False)}\n\n"
	f"User Aspect Ratio Selection:\n{aspect_ratio}\n\n"
	"Apply the instructions above to the supplied inputs and reference images. "
	"Output only the required two-field JSON object."
	)
	content.append({"type": "text", "text": user_input})
	messages = [{"role": "user", "content": content}]
	```

	### Output

	```json
	{
	"expanded_caption": "<one paragraph describing the intended edit>",
	"target_aspect_ratio": "3:2"
	}
	```

	The description identifies source subjects, states what is preserved or changed,
	and describes new content. Descriptive prose is English; literal text retains the
	language you request. `target_aspect_ratio` is a positive-integer `W:H` string.
	If you select an explicit ratio, the model preserves it exactly. If you select
	`adaptive`, the model determines a numeric ratio for the intended edited image.

	## Use with Diffusers

	MiniMax-H3-Image-PE can also run locally in Transformers through the
	[`diffusers/minimax-h3-image-pe-blocks`](https://huggingface.co/diffusers/minimax-h3-image-pe-blocks)
	Modular Diffusers blocks. The blocks use the released prompts and request
	parameters for T2I PE and Image editing PE, and XGrammar constrains the answer
	to the JSON schema.

	### Load MiniMax-H3-Image-PE

	```bash
	pip install -U diffusers transformers xgrammar bitsandbytes kernels flash-linear-attention
	```

	```python
	import torch
	from diffusers import ModularPipeline

	pe = ModularPipeline.from_pretrained("diffusers/minimax-h3-image-pe-blocks", trust_remote_code=True)
	pe.load_components(dtype=torch.bfloat16, device_map="cuda")
	```

	The FP4 weights stay in 4-bit and use about 19 GiB of GPU memory. GPUs with
	native FP4 support run the NVFP4 weights directly; other GPUs use bitsandbytes
	FP4.

	### Expand a prompt

	Pass a request to run T2I PE:

	```python
	state = pe(prompt="An orange tabby cat sleeping on a sunlit windowsill.")
	print(state.get("prompt"), state.get("aspect_ratio"))
	```

	Pass reference images to run Image editing PE. Refer to the images in their
	supplied order:

	```python
	state = pe(
	prompt="Replace the bag in the first image with the bag in the second image.",
	image=["source.png", "bag.png"],
	aspect_ratio="adaptive",
	)
	print(state.get("prompt"), state.get("aspect_ratio"))
	```

	### Inputs and outputs

	\| Name \| Description \|
	\| --- \| --- \|
	\| `prompt` \| Input: the request or editing instruction. Output: the expanded caption. \|
	\| `image` \| One or more reference images (PIL images, paths or URLs). Selects Image editing PE. \|
	\| `aspect_ratio` \| Input, Image editing PE only: `adaptive` or an explicit `W:H` ratio. Output: the target ratio. \|
	\| `enable_thinking` \| Reasoning before the answer, `True` by default as in the released request. \|
	\| `max_new_tokens` \| Token budget, including thinking and the final answer. \|
	\| `seed` \| Seed for a reproducible expansion. \|
	\| `reasoning` \| Output: the model's reasoning. \|

	Activations run in bf16, so outputs are not identical to the SGLang deployment
	above.

	## License

	- MiniMax-H3-Image-PE is part of MiniMax-H3-Image and is released under the [MiniMax-H3-Image Community License Agreement](https://huggingface.co/MiniMaxAI/MiniMax-H3-Image/blob/main/LICENSE).
	- MiniMax-H3-Image-PE is derived from [Qwen3.8-27B](https://huggingface.co/Qwen/Qwen3.8-27B), which is licensed under the Apache 2.0 License.
	- The separate written authorization described in Section IV of the license is requested through [platform.minimax.io/license](https://platform.minimax.io/license).

	## Contact Us

	Contact us at [model@minimax.io](mailto:model@minimax.io).