### Install Gradio

Source: https://github.com/tencent-hunyuan/hunyuanimage-3.0/blob/main/README.md

Install the Gradio library, which is required to launch the interactive web interface for text-to-image generation. A specific version is recommended.

```bash
pip install gradio>=4.21.0
```

--------------------------------

### Install FlashInfer

Source: https://github.com/tencent-hunyuan/hunyuanimage-3.0/blob/main/README.md

Install FlashInfer version 0.5.0. Ensure CUDA and GCC versions are compatible for kernel compilation.

```bash
pip install flashinfer-python==0.5.0
```

--------------------------------

### Launch vLLM Server

Source: https://github.com/tencent-hunyuan/hunyuanimage-3.0/blob/main/vllm_infer/README.md

Starts the vLLM server for the Hunyuan Image3 API. Ensure the model path is correctly specified.

```bash
sh vllm_infer/run_vllm_server.sh /path/to/model
```

--------------------------------

### Install Hunyuan Image3 and Dependencies

Source: https://github.com/tencent-hunyuan/hunyuanimage-3.0/blob/main/vllm_infer/README.md

Installs the Hunyuan Image3 package, other required Python dependencies, and vLLM from a specific commit.

```bash
# Install hunyuan_image_3 as a package
git clone https://github.com/Tencent-Hunyuan/HunyuanImage-3.0
cd HunyuanImage-3.0/
pip install -e .

# Install other dependencies
pip install apache-tvm-ffi==0.1.0b15
pip install diffusers transformers accelerate

# Install vLLM from specific commit
git clone --branch feature/hunyuan_image_3.0 https://github.com/kippergong/vllm.git
cd vllm
VLLM_USE_PRECOMPILED=1 pip install --editable .
cd ..

# Launch the vLLM server
sh vllm_infer/run_vllm_server.sh /path/to/model
```

--------------------------------

### Install Tencent Cloud SDK

Source: https://context7.com/tencent-hunyuan/hunyuanimage-3.0/llms.txt

Optional installation of the Tencent Cloud SDK for DeepSeek prompt enhancement, applicable to the base T2I model only.

```bash
pip install -i https://mirrors.tencent.com/pypi/simple/ --upgrade tencentcloud-sdk-python
```

--------------------------------

### Launch Gradio Interactive Demo

Source: https://context7.com/tencent-hunyuan/hunyuanimage-3.0/llms.txt

Launch a browser-accessible web UI for interactive text-to-image generation using the base T2I model. Configure environment variables for model path, GPUs, host, and port. Install Gradio if not already present. Performance optimizations can be applied.

```bash
# Configure environment
export MODEL_ID="./HunyuanImage-3"   # path to base T2I model
export GPUS="0,1,2,3"                # GPU IDs to use
export HOST="0.0.0.0"
export PORT="7860"

# Install Gradio
pip install "gradio>=4.21.0"

# Basic launch
sh run_app.sh

# With performance optimizations
sh run_app.sh --moe-impl flashinfer --attn-impl flash_attention_2

# Access at: http://localhost:7860
```

--------------------------------

### Launch vLLM HTTP Server for HunyuanImage-3.0

Source: https://context7.com/tencent-hunyuan/hunyuanimage-3.0/llms.txt

Start the vLLM server with the HunyuanImage-3.0 task enabled. Specify the model path and configure server parameters like GPU utilization and sequence limits.

```bash
# 2. Launch the server (serves on http://localhost:8000)
export VLLM_ENABLE_HUNYUAN_IMAGE3_TASK="1"
sh vllm_infer/run_vllm_server.sh /path/to/HunyuanImage-3-model
# Equivalent manual command:
# vllm serve /path/to/model \
#   --trust-remote-code \
#   --served-model-name vllm_hunyuan_image3 \
#   --max-model-len 10000 \
#   --gpu-memory-utilization 0.6 \
#   --max-num-seqs 1 \
#   --enforce-eager \
#   -tp 8
```

--------------------------------

### Install HunyuanImage-3.0 Dependencies

Source: https://context7.com/tencent-hunyuan/hunyuanimage-3.0/llms.txt

Installs all required Python dependencies for HunyuanImage-3.0 from the requirements.txt file.

```bash
pip install -r requirements.txt
```

--------------------------------

### Install Custom vLLM for HunyuanImage-3.0

Source: https://context7.com/tencent-hunyuan/hunyuanimage-3.0/llms.txt

Clone the custom vLLM branch and install it as an editable package. This is a prerequisite for serving HunyuanImage-3.0 with vLLM.

```bash
# 1. Install custom vLLM
git clone --branch feature/hunyuan_image_3.0 https://github.com/kippergong/vllm.git
cd vllm && VLLM_USE_PRECOMPILED=1 pip install --editable . && cd ..
```

--------------------------------

### Install Dependencies for HunyuanImage-3.0

Source: https://github.com/tencent-hunyuan/hunyuanimage-3.0/blob/main/README.md

Installs PyTorch with CUDA support, the tencentcloud-sdk for prompt enhancement (if needed), and other project dependencies. Ensure you have Python 3.12+ and CUDA 12.8 installed.

```bash
# 1. First install PyTorch (CUDA 12.8 Version)
pip install torch==2.8.0 torchvision==0.23.0 torchaudio==2.8.0 --index-url https://download.pytorch.org/whl/cu128

# 2. Install tencentcloud-sdk for Prompt Enhancement (PE) only for HunyuanImage-3.0 not HunyuanImage-3.0-Instruct
pip install -i https://mirrors.tencent.com/pypi/simple/ --upgrade tencentcloud-sdk-python

# 3. Then install other dependencies
pip install -r requirements.txt
```

--------------------------------

### Docker Deployment for vLLM Service

Source: https://context7.com/tencent-hunyuan/hunyuanimage-3.0/llms.txt

Build a Docker image for the vLLM service and run it as a container. Mount local model weights into the container and expose the API on port 8000. Ensure you have Docker installed and the model weights available locally.

```bash
# Build image
docker build -t hunyuan_image3_vllm -f docker/hyimage3_vllm.Dockerfile .

# Run container, mounting local model weights into /model
docker run --gpus all -it -p 8000:8000 \
    --mount type=bind,source=/path/to/local/model,target=/model \
    hunyuan_image3_vllm \
    sh HunyuanImage-3.0/vllm_infer/run_vllm_server.sh /model

# The HTTP API is now available at http://localhost:8000
```

--------------------------------

### Install PyTorch with CUDA 12.8

Source: https://context7.com/tencent-hunyuan/hunyuanimage-3.0/llms.txt

Installs the specified version of PyTorch with CUDA 12.8 support. Ensure your system meets the CUDA version requirements.

```bash
pip install torch==2.8.0 torchvision==0.23.0 torchaudio==2.8.0 \
    --index-url https://download.pytorch.org/whl/cu128
```

--------------------------------

### Load HunyuanImage-3.0 Model

Source: https://context7.com/tencent-hunyuan/hunyuanimage-3.0/llms.txt

Loads a HunyuanImage-3.0 checkpoint from a local directory using Hugging Face Transformers. Ensure the model weights are downloaded first. The `attn_implementation` and `moe_impl` parameters can be adjusted based on installed libraries.

```python
from transformers import AutoModelForCausalLM

# Download weights first:
# hf download tencent/HunyuanImage-3.0-Instruct --local-dir ./HunyuanImage-3-Instruct
model_id = "./HunyuanImage-3-Instruct"

model = AutoModelForCausalLM.from_pretrained(
    model_id,
    attn_implementation="sdpa",        # or "flash_attention_2" if FlashAttention installed
    trust_remote_code=True,
    torch_dtype="auto",                # auto-selects bfloat16
    device_map="auto",                 # distributes across available GPUs
    moe_impl="flashinfer",             # or "eager" if FlashInfer not installed
    moe_drop_tokens=True,
)
model.load_tokenizer(model_id)         # must be called after from_pretrained
```

--------------------------------

### Run Demo with 8 Sampling Steps

Source: https://github.com/tencent-hunyuan/hunyuanimage-3.0/blob/main/README.md

Execute this script after downloading the distilled model to run the demo with a reduced number of sampling steps (8).

```bash
export MODEL_PATH="./HunyuanImage-3-Instruct-Distil"
bash run_demo_instruct_Distil.sh
```

--------------------------------

### Build and Run Docker Container

Source: https://github.com/tencent-hunyuan/hunyuanimage-3.0/blob/main/vllm_infer/README.md

Builds the Docker image for Hunyuan Image3 with vLLM and runs it, exposing the server port and mounting the model directory.

```bash
# Build the Docker image
docker build -t hunyuan_image3_vllm -f docker/hyimage3_vllm.Dockerfile
# Run the Docker container
docker run --gpus all -it -p 8000:8000 hunyuan_image3_vllm \
    --mount type=bind,source=/path/to/model,target=/model \
    sh HunyuanImage-3.0/vllm_infer/run_vllm_server.sh /model
```

--------------------------------

### Run HunyuanImage-3.0 Demo

Source: https://github.com/tencent-hunyuan/hunyuanimage-3.0/blob/main/README.md

Execute the demo script for HunyuanImage-3.0. Ensure the MODEL_PATH environment variable is set correctly.

```bash
export MODEL_PATH="./HunyuanImage-3-Instruct"
bash run_demo_instruct.sh
```

--------------------------------

### Configure Environment for Gradio Demo

Source: https://github.com/tencent-hunyuan/hunyuanimage-3.0/blob/main/README.md

Set environment variables for the Gradio demo, including the model path, GPU configuration, and host/port settings. The model path is required, while GPU, host, and port are optional.

```bash
# Set your model path
export MODEL_ID="path/to/your/model"

# Optional: Configure GPU usage (default: 0,1,2,3)
export GPUS="0,1,2,3"

# Optional: Configure host and port (default: 0.0.0.0:443)
export HOST="0.0.0.0"
export PORT="443"
```

--------------------------------

### Download Model Weights Locally

Source: https://github.com/tencent-hunyuan/hunyuanimage-3.0/blob/main/README.md

Download model weights from HuggingFace for local use. This step is required after cloning the repository.

```bash
# Download from HuggingFace
hf download tencent/HunyuanImage-3.0-Instruct --local-dir ./HunyuanImage-3-Instruct
```

--------------------------------

### Download Model Weights with HuggingFace CLI

Source: https://github.com/tencent-hunyuan/hunyuanimage-3.0/blob/main/README.md

Download model weights from HuggingFace using the CLI. Rename the directory to avoid issues with Transformers loading.

```bash
# Download from HuggingFace and rename the directory.
# Notice that the directory name should not contain dots, which may cause issues when loading using Transformers.
hf download tencent/HunyuanImage-3.0-Instruct --local-dir ./HunyuanImage-3-Instruct
```

--------------------------------

### Run Image Generation with PE

Source: https://github.com/tencent-hunyuan/hunyuanimage-3.0/blob/main/README.md

Execute image generation using the command line with specified parameters. Ensure DeepSeek API keys and model path are set as environment variables.

```bash
export DEEPSEEK_KEY_ID="your_deepseek_key_id"
export DEEPSEEK_KEY_SECRET="your_deepseek_key_secret"
export MODEL_PATH="./HunyuanImage-3"
python3 run_image_gen.py \
    --model-id $MODEL_PATH \
    --verbose 1 \
    --prompt "A brown and white dog is running on the grass" \
    --bot-task image \
    --image-size "1024x1024" \
    --save ./image.png \
    --moe-impl flashinfer \
    --rewrite 1
```

--------------------------------

### Download HunyuanImage-3.0-Instruct-Distil Model

Source: https://github.com/tencent-hunyuan/hunyuanimage-3.0/blob/main/README.md

Use this command to download the distilled version of the model from HuggingFace for use with fewer sampling steps.

```bash
hf download tencent/HunyuanImage-3.0-Instruct-Distil --local-dir ./HunyuanImage-3-Instruct-Distil
```

--------------------------------

### Enable Taylor Cache Acceleration via CLI

Source: https://context7.com/tencent-hunyuan/hunyuanimage-3.0/llms.txt

Use the `--use-taylor-cache` flag with specified interval and order for diffusion step-skipping optimization. Adjust enhancement steps as needed.

```bash
python3 run_image_gen.py \
    --model-id ./HunyuanImage-3-Instruct \
    --prompt "A hyperrealistic portrait of an astronaut on Mars" \
    --bot-task think_recaption \
    --image-size "1024x1024" \
    --diff-infer-steps 50 \
    --use-taylor-cache \
    --taylor-cache-interval 5 \
    --taylor-cache-order 2 \
    --taylor-cache-enable-first-enhance \
    --taylor-cache-first-enhance-steps 3 \
    --taylor-cache-enable-tailing-enhance \
    --taylor-cache-tailing-enhance-steps 1 \
    --moe-impl flashinfer \
    --save ./taylor_cached_output.png
```

--------------------------------

### Model Loading - HunyuanImage3ForCausalMM.from_pretrained

Source: https://context7.com/tencent-hunyuan/hunyuanimage-3.0/llms.txt

Loads a HunyuanImage-3.0 checkpoint from a local directory using the Hugging Face `AutoModelForCausalLM` / `HunyuanImage3ForCausalMM` interface. Ensure model weights are downloaded first.

```APIDOC
## Model Loading — `HunyuanImage3ForCausalMM.from_pretrained`

Load a HunyuanImage-3.0 checkpoint from a local directory using the Hugging Face `AutoModelForCausalLM` / `HunyuanImage3ForCausalMM` interface. The model directory must be downloaded first and must not contain dots in its name.

```python
from transformers import AutoModelForCausalLM

# Download weights first:
# hf download tencent/HunyuanImage-3.0-Instruct --local-dir ./HunyuanImage-3-Instruct
model_id = "./HunyuanImage-3-Instruct"

model = AutoModelForCausalLM.from_pretrained(
    model_id,
    attn_implementation="sdpa",        # or "flash_attention_2" if FlashAttention installed
    trust_remote_code=True,
    torch_dtype="auto",                # auto-selects bfloat16
    device_map="auto",                 # distributes across available GPUs
    moe_impl="flashinfer",             # or "eager" if FlashInfer not installed
    moe_drop_tokens=True,
)
model.load_tokenizer(model_id)         # must be called after from_pretrained
```
```

--------------------------------

### Download HunyuanImage-3.0 Model Weights

Source: https://github.com/tencent-hunyuan/hunyuanimage-3.0/blob/main/README.md

Download the main model weights from HuggingFace. Ensure the local directory name does not contain dots to avoid potential loading issues with Transformers.

```bash
# Download from HuggingFace and rename the directory.
# Notice that the directory name should not contain dots, which may cause issues when loading using Transformers.
hf download tencent/HunyuanImage-3.0 --local-dir ./HunyuanImage-3
```

--------------------------------

### Multi-Image Fusion via CLI

Source: https://context7.com/tencent-hunyuan/hunyuanimage-3.0/llms.txt

Execute multi-image fusion from the command line by providing a comma-separated list of image paths to the `--image` argument.

```bash
# --- Multi-image fusion ---
python3 run_image_gen.py \
    --model-id $MODEL_PATH \
    --prompt "Have the cat in image 1 take a selfie with the cat in image 2, background from image 3" \
    --image "img1.png,img2.png,img3.png" \
    --bot-task think_recaption \
    --image-size auto \
    --use-system-prompt en_unified \
    --infer-align-image-size \
    --moe-impl flashinfer \
    --save ./cats_selfie.png
```

--------------------------------

### Text-to-Image Generation via CLI

Source: https://context7.com/tencent-hunyuan/hunyuanimage-3.0/llms.txt

Use the `run_image_gen.py` script for text-to-image generation. Specify model path, prompt, image size, and other parameters as command-line arguments.

```bash
export MODEL_PATH="./HunyuanImage-3-Instruct"

# --- Text-to-image with CoT reasoning ---
python3 run_image_gen.py \
    --model-id $MODEL_PATH \
    --prompt "A cyberpunk city at night with neon reflections on wet pavement" \
    --bot-task think_recaption \
    --image-size "1280x768" \
    --use-system-prompt en_unified \
    --seed 42 \
    --reproduce \
    --diff-infer-steps 50 \
    --moe-impl flashinfer \
    --save ./output_t2i.png \
    --verbose 2
```

--------------------------------

### Enhance Prompts with DeepSeek API via Python

Source: https://context7.com/tencent-hunyuan/hunyuanimage-3.0/llms.txt

Use `DeepSeekClient` to rewrite sparse prompts for the base text-to-image model. Requires Tencent Cloud API credentials set as environment variables.

```python
import os
from PE.deepseek import DeepSeekClient
from PE.system_prompt import system_prompt_universal

# Set credentials via environment variables
key_id = os.environ["DEEPSEEK_KEY_ID"]
key_secret = os.environ["DEEPSEEK_KEY_SECRET"]

client = DeepSeekClient(key_id, key_secret)

original_prompt = "dog in park"
enhanced_prompt, reasoning = client.run_single_recaption(
    system_prompt=system_prompt_universal,
    input_prompt=original_prompt,
)

print("Original:", original_prompt)
print("Enhanced:", enhanced_prompt)
# Enhanced: "A golden retriever playfully chasing a ball across a sunlit..."
print("Reasoning:", reasoning[:200])

# Use the enhanced prompt with the base model
from transformers import AutoModelForCausalLM
model = AutoModelForCausalLM.from_pretrained(
    "./HunyuanImage-3", trust_remote_code=True,
    torch_dtype="auto", device_map="auto", moe_impl="eager",
)
model.load_tokenizer("./HunyuanImage-3")
image = model.generate_image(prompt=enhanced_prompt, stream=True)
image.save("enhanced_dog.png")
```

--------------------------------

### Run Image Generation Demo

Source: https://github.com/tencent-hunyuan/hunyuanimage-3.0/blob/main/README.md

Execute the main image generation script. This command uses several arguments to specify the model path, prompt, task type, image size, and output path. It also configures the MoE implementation.

```bash
# Without PE
export MODEL_PATH="./HunyuanImage-3"
python3 run_image_gen.py \
    --model-id $MODEL_PATH \
    --verbose 1 \
    --prompt "A brown and white dog is running on the grass" \
    --bot-task image \
    --image-size "1024x1024" \
    --save ./image.png \
    --moe-impl flashinfer
```

--------------------------------

### Generate Basic Image

Source: https://github.com/tencent-hunyuan/hunyuanimage-3.0/blob/main/vllm_infer/README.md

Generates an image using the default settings with a specified prompt.

```bash
python openai_client.py --prompt "panda eating bamboo in forest"
```

--------------------------------

### Enhance Prompts with DeepSeek API via CLI

Source: https://context7.com/tencent-hunyuan/hunyuanimage-3.0/llms.txt

Leverage the `--rewrite 1` flag in the CLI to enable prompt rewriting using the DeepSeek API for the base text-to-image model. Ensure API keys are exported as environment variables.

```bash
export DEEPSEEK_KEY_ID="your_key_id"
export DEEPSEEK_KEY_SECRET="your_key_secret"
python3 run_image_gen.py \
    --model-id ./HunyuanImage-3 \
    --prompt "dog in park" \
    --bot-task image \
    --image-size "1024x1024" \
    --rewrite 1 \
    --moe-impl flashinfer \
    --save ./rewritten_dog.png
```

--------------------------------

### Initialize HunyuanImage Model

Source: https://context7.com/tencent-hunyuan/hunyuanimage-3.0/llms.txt

Load the HunyuanImage model and tokenizer. Ensure `trust_remote_code` is set to `True` and specify `torch_dtype` and `device_map` for optimal performance.

```python
from transformers import AutoModelForCausalLM

model_id = "./HunyuanImage-3-Instruct"
model = AutoModelForCausalLM.from_pretrained(
    model_id, trust_remote_code=True, torch_dtype="auto",
    device_map="auto", moe_impl="flashinfer", moe_drop_tokens=True,
)
model.load_tokenizer(model_id)
```

--------------------------------

### Generate Images with OpenAI Client

Source: https://github.com/tencent-hunyuan/hunyuanimage-3.0/blob/main/vllm_infer/README.md

Uses the provided OpenAI client script to generate images based on a text prompt. The server must be running.

```bash
python openai_client.py --prompt "your image description"
```

--------------------------------

### Faster Inference with Distil Checkpoint via CLI

Source: https://context7.com/tencent-hunyuan/hunyuanimage-3.0/llms.txt

Utilize the Distil checkpoint for faster inference by setting `diff_infer_steps` to 8. Ensure the `MODEL_PATH` points to the Distil model.

```bash
# --- Faster inference: Distil checkpoint (8 steps) ---
export MODEL_PATH="./HunyuanImage-3-Instruct-Distil"
python3 run_image_gen.py \
    --model-id $MODEL_PATH \
    --prompt "A surrealist oil painting of a melting clock in a desert" \
    --bot-task think_recaption \
    --diff-infer-steps 8 \
    --use-system-prompt en_unified \
    --seed 5 \
    --moe-impl flashinfer \
    --save ./distil_output.png
```

--------------------------------

### Load and Run HunyuanImage-3.0 with Transformers

Source: https://github.com/tencent-hunyuan/hunyuanimage-3.0/blob/main/README.md

Load the HunyuanImage-3.0 model using Transformers for image-to-image generation. Ensure correct model path and generation parameters are set.

```python
from transformers import AutoModelForCausalLM

# Load the model
model_id = "./HunyuanImage-3-Instruct"
# Currently we can not load the model using HF model_id `tencent/HunyuanImage-3.0-Instruct` directly 
# due to the dot in the name.

kwargs = dict(
    attn_implementation="sdpa", 
    trust_remote_code=True,
    torch_dtype="auto",
    device_map="auto",
    moe_impl="eager",   # Use "flashinfer" if FlashInfer is installed
    moe_drop_tokens=True,
)

model = AutoModelForCausalLM.from_pretrained(model_id, **kwargs)
model.load_tokenizer(model_id)

# Image-to-Image generation (TI2I)
prompt = "基于图一的logo，参考图二中冰箱贴的材质，制作一个新的冰箱贴"

input_img1 = "./assets/demo_instruct_imgs/input_1_0.png"
input_img2 = "./assets/demo_instruct_imgs/input_1_1.png"
imgs_input = [input_img1, input_img2]

cot_text, samples = model.generate_image(
    prompt=prompt,
    image=imgs_input,
    seed=42,
    image_size="auto",
    use_system_prompt="en_unified",
    bot_task="think_recaption",  # Use "think_recaption" for reasoning and enhancement
    infer_align_image_size=True,  # Align output image size to input image size
    diff_infer_steps=50, 
    verbose=2
)

# Save the generated image
samples[0].save("image_edit.png")
```

--------------------------------

### Launch Gradio App

Source: https://github.com/tencent-hunyuan/hunyuanimage-3.0/blob/main/README.md

Run the Gradio application using the provided shell script. Two variants are shown: a basic launch and one with performance optimizations.

```bash
sh run_app.sh
```

```bash
# Use both optimizations for maximum performance
sh run_app.sh --moe-impl flashinfer --attn-impl flash_attention_2
```

--------------------------------

### Direct HTTP Call with Requests

Source: https://context7.com/tencent-hunyuan/hunyuanimage-3.0/llms.txt

Make a direct HTTP POST request to the vLLM server for image generation. Ensure the server is running and accessible at http://localhost:8000. The response contains a base64 encoded image that needs to be decoded and saved.

```python
import requests, json, base64

payload = {
    "model": "vllm_hunyuan_image3",
    "messages": [
        {"role": "system", "content": ""},
        {"role": "user", "content": "A futuristic skyline at dusk"}
    ],
    "max_completion_tokens": 1,
    "temperature": 0,
    "seed": 123,
    "chat_template": (
        "{%% for message in messages %%}"
        "{%% if message['role'] == 'user' %%}"
        "<|startoftext|>{{ message['content'] }}"
        "{%% endif %%}{%%% endfor %%}"
    ),
    "task_type": "hunyuan_image3",
    "task_extra_kwargs": {
        "diff_infer_steps": 50,
        "use_system_prompt": "None",
        "bot_task": "image",
        "image_size": "1024x1024",
    },
}

resp = requests.post(
    "http://localhost:8000/v1/chat/completions",
    data=json.dumps(payload),
    headers={"Content-Type": "application/json"},
    timeout=600,
)
assert resp.status_code == 200, resp.text

# Decode and save the returned base64 image
img_b64 = resp.json()["image"]
if "," in img_b64:
    img_b64 = img_b64.split(",")[1]
with open("vllm_output.png", "wb") as f:
    f.write(base64.b64decode(img_b64))
print("Saved vllm_output.png")
```

--------------------------------

### Download HunyuanImage-3.0 Model Weights

Source: https://context7.com/tencent-hunyuan/hunyuanimage-3.0/llms.txt

Use the `hf download` command to download model weights for different HunyuanImage-3.0 variants. Specify the HuggingFace ID and a local directory for storage.

```bash
hf download tencent/HunyuanImage-3.0-Instruct         --local-dir ./HunyuanImage-3-Instruct
```

```bash
hf download tencent/HunyuanImage-3.0                  --local-dir ./HunyuanImage-3
```

```bash
hf download tencent/HunyuanImage-3.0-Instruct-Distil  --local-dir ./HunyuanImage-3-Instruct-Distil
```

--------------------------------

### Load and Generate Image with Transformers

Source: https://github.com/tencent-hunyuan/hunyuanimage-3.0/blob/main/README.md

This Python script demonstrates how to load the HunyuanImage-3.0 model using the Transformers library and generate an image from a text prompt. Ensure the model is downloaded to the specified local path.

```python
from transformers import AutoModelForCausalLM

# Load the model
model_id = "./HunyuanImage-3"
# Currently we can not load the model using HF model_id `tencent/HunyuanImage-3.0` directly 
# due to the dot in the name.

kwargs = dict(
    attn_implementation="sdpa",     # Use "flash_attention_2" if FlashAttention is installed
    trust_remote_code=True,
    torch_dtype="auto",
    device_map="auto",
    moe_impl="eager",   # Use "flashinfer" if FlashInfer is installed
)

model = AutoModelForCausalLM.from_pretrained(model_id, **kwargs)
model.load_tokenizer(model_id)

# generate the image
prompt = "A brown and white dog is running on the grass"
image = model.generate_image(prompt=prompt, stream=True)
image.save("image.png")
```

--------------------------------

### Command-Line Interface for Image Generation

Source: https://context7.com/tencent-hunyuan/hunyuanimage-3.0/llms.txt

Utilize the `run_image_gen.py` script for text-to-image and image-to-image tasks directly from the command line without writing Python code.

```APIDOC
## Command-Line Interface — `run_image_gen.py`

The `run_image_gen.py` script provides a full CLI to run inference for both T2I and TI2I tasks without writing Python code.

```bash
export MODEL_PATH="./HunyuanImage-3-Instruct"

# --- Text-to-image with CoT reasoning ---
python3 run_image_gen.py \
    --model-id $MODEL_PATH \
    --prompt "A cyberpunk city at night with neon reflections on wet pavement" \
    --bot-task think_recaption \
    --image-size "1280x768" \
    --use-system-prompt en_unified \
    --seed 42 \
    --reproduce \
    --diff-infer-steps 50 \
    --moe-impl flashinfer \
    --save ./output_t2i.png \
    --verbose 2

# --- Image-to-image editing ---
python3 run_image_gen.py \
    --model-id $MODEL_PATH \
    --prompt "Make the cat wear a wizard hat and a starry cloak" \
    --image ./cat.jpg \
    --bot-task think_recaption \
    --image-size auto \
    --use-system-prompt en_unified \
    --infer-align-image-size \
    --seed 99 \
    --moe-impl flashinfer \
    --save ./cat_wizard.png

# --- Multi-image fusion ---
python3 run_image_gen.py \
    --model-id $MODEL_PATH \
    --prompt "Have the cat in image 1 take a selfie with the cat in image 2, background from image 3" \
    --image "img1.png,img2.png,img3.png" \
    --bot-task think_recaption \
    --image-size auto \
    --use-system-prompt en_unified \
    --infer-align-image-size \
    --moe-impl flashinfer \
    --save ./cats_selfie.png

# --- Faster inference: Distil checkpoint (8 steps) ---
export MODEL_PATH="./HunyuanImage-3-Instruct-Distil"
python3 run_image_gen.py \
    --model-id $MODEL_PATH \
    --prompt "A surrealist oil painting of a melting clock in a desert" \
    --bot-task think_recaption \
    --diff-infer-steps 8 \
    --use-system-prompt en_unified \
    --seed 5 \
    --moe-impl flashinfer \
    --save ./distil_output.png
```
```

--------------------------------

### Enable Taylor Cache Acceleration via Python API

Source: https://context7.com/tencent-hunyuan/hunyuanimage-3.0/llms.txt

Configure Taylor Cache settings directly within the `generate_image` method for diffusion step-skipping optimization. Ensure correct parameters for interval, order, and enhancement steps.

```python
# Python API equivalent
cot_text, samples = model.generate_image(
    prompt="A hyperrealistic portrait of an astronaut on Mars",
    seed=1,
    image_size="1024x1024",
    bot_task="think_recaption",
    use_system_prompt="en_unified",
    diff_infer_steps=50,
    use_taylor_cache=True,
    taylor_cache_interval=5,
    taylor_cache_order=2,
    taylor_cache_enable_first_enhance=True,
    taylor_cache_first_enhance_steps=3,
    taylor_cache_enable_tailing_enhance=True,
    taylor_cache_tailing_enhance_steps=1,
    taylor_cache_low_freqs_order=2,
    taylor_cache_high_freqs_order=2,
)
samples[0].save("taylor_cached_output.png")
```

--------------------------------

### Image-to-Image Editing via CLI

Source: https://context7.com/tencent-hunyuan/hunyuanimage-3.0/llms.txt

Perform image-to-image editing using the CLI script. Provide the input image path using the `--image` flag and specify editing parameters.

```bash
# --- Image-to-image editing ---
python3 run_image_gen.py \
    --model-id $MODEL_PATH \
    --prompt "Make the cat wear a wizard hat and a starry cloak" \
    --image ./cat.jpg \
    --bot-task think_recaption \
    --image-size auto \
    --use-system-prompt en_unified \
    --infer-align-image-size \
    --seed 99 \
    --moe-impl flashinfer \
    --save ./cat_wizard.png
```

--------------------------------

### Simple Text-to-Image Generation

Source: https://context7.com/tencent-hunyuan/hunyuanimage-3.0/llms.txt

Performs text-to-image generation using the loaded HunyuanImage-3.0 model. The `generate_image` method accepts a prompt, seed, image size, and various generation parameters. The output includes Chain-of-Thought reasoning and a list of PIL images.

```python
from transformers import AutoModelForCausalLM

model_id = "./HunyuanImage-3-Instruct"
model = AutoModelForCausalLM.from_pretrained(
    model_id, trust_remote_code=True, torch_dtype="auto",
    device_map="auto", moe_impl="flashinfer", moe_drop_tokens=True,
)
model.load_tokenizer(model_id)

# --- Simple text-to-image ---
cot_text, samples = model.generate_image(
    prompt="A photorealistic red fox sitting in a snowy forest at sunset",
    seed=42,
    image_size="1024x1024",            # or "auto", "16:9", "1280x768"
    use_system_prompt="en_unified",    # system prompt preset
    bot_task="think_recaption",        # think -> rewrite -> generate
    diff_infer_steps=50,               # diffusion denoising steps
    verbose=2,
)

samples[0].save("fox_t2i.png")
print("CoT reasoning:", cot_text)
# Expected: cot_text contains <think>...</think><recaption>...</recaption> XML
```

--------------------------------

### Generate Image via Python Client with vLLM Server

Source: https://context7.com/tencent-hunyuan/hunyuanimage-3.0/llms.txt

Interact with the vLLM-served HunyuanImage-3.0 model using an OpenAI-compatible Python client. Specify prompt, dimensions, seed, and bot task.

```bash
# 3. Generate an image via the Python client
python vllm_infer/openai_client.py \
    --prompt "A panda eating bamboo in a lush forest" \
    --width 1024 --height 1024 \
    --seed 42 \
    --bot-task image
# Saves output to output.png

# Custom size
python vllm_infer/openai_client.py \
    --prompt "Sunset over a calm ocean" \
    --width 1280 --height 768
```

--------------------------------

### DeepSeek Prompt Enhancement

Source: https://context7.com/tencent-hunyuan/hunyuanimage-3.0/llms.txt

Improve prompt quality for the base text-to-image model by rewriting sparse prompts using Tencent Cloud's DeepSeek API. This requires valid Tencent Cloud API credentials.

```APIDOC
## DeepSeek Prompt Enhancement — `DeepSeekClient`

For the **base** text-to-image model (not Instruct), prompt quality can be improved by rewriting sparse prompts through Tencent Cloud's DeepSeek API. Requires Tencent Cloud API credentials.

### Python API Example
```python
import os
from PE.deepseek import DeepSeekClient
from PE.system_prompt import system_prompt_universal

# Set credentials via environment variables
key_id = os.environ["DEEPSEEK_KEY_ID"]
key_secret = os.environ["DEEPSEEK_KEY_SECRET"]

client = DeepSeekClient(key_id, key_secret)

original_prompt = "dog in park"
enhanced_prompt, reasoning = client.run_single_recaption(
    system_prompt=system_prompt_universal,
    input_prompt=original_prompt,
)

print("Original:", original_prompt)
print("Enhanced:", enhanced_prompt)
# Enhanced: "A golden retriever playfully chasing a ball across a sunlit..."
print("Reasoning:", reasoning[:200])

# Use the enhanced prompt with the base model
from transformers import AutoModelForCausalLM
model = AutoModelForCausalLM.from_pretrained(
    "./HunyuanImage-3", trust_remote_code=True,
    torch_dtype="auto", device_map="auto", moe_impl="eager",
)
model.load_tokenizer("./HunyuanImage-3")
image = model.generate_image(prompt=enhanced_prompt, stream=True)
image.save("enhanced_dog.png")
```

### CLI Equivalent
```bash
export DEEPSEEK_KEY_ID="your_key_id"
export DEEPSEEK_KEY_SECRET="your_key_secret"
python3 run_image_gen.py \
    --model-id ./HunyuanImage-3 \
    --prompt "dog in park" \
    --bot-task image \
    --image-size "1024x1024" \
    --rewrite 1 \
    --moe-impl flashinfer \
    --save ./rewritten_dog.png
```
```

--------------------------------

### HunyuanImage3AppPipeline for Gradio

Source: https://context7.com/tencent-hunyuan/hunyuanimage-3.0/llms.txt

Backend pipeline for the Gradio web app, wrapping HunyuanImage3ForCausalMM. Supports multi-turn conversations and streaming image generation. Configure pipeline arguments and use the `generate` method to stream results, handling text, image, and flag chunks.

```python
import argparse
from app.pipeline import HunyuanImage3AppPipeline

args = argparse.Namespace(
    model_id="./HunyuanImage-3",
    attn_impl="sdpa",
    moe_impl="flashinfer",
)
pipeline = HunyuanImage3AppPipeline(args)

# Build message history in Gradio format
history = [
    {"role": "user", "content": "Generate a photo of a white cat on a red sofa"}
]

# Stream results (yields dicts with role/type/value)
for chunk in pipeline.generate(
    history,
    seed=10,
    image_size="1024x1024",
    bot_task="image",
    context_mode="single_round",
    verbose=1,
):
    if chunk["type"] == "text":
        print(chunk["value"], end="", flush=True)
    elif chunk["type"] == "image":
        pil_img = chunk["value"]
        pil_img.save("app_output.png")
        print("\nImage saved.")
    elif chunk["type"] == "flag":
        print("\n[Image generation starting...]")
```

--------------------------------

### Clone HunyuanImage-3.0 Repository

Source: https://github.com/tencent-hunyuan/hunyuanimage-3.0/blob/main/README.md

Clone the HunyuanImage-3.0 repository from GitHub to set up for local usage.

```bash
git clone https://github.com/Tencent-Hunyuan/HunyuanImage-3.0.git
cd HunyuanImage-3.0/
```

--------------------------------

### Single Image Editing with HunyuanImage

Source: https://context7.com/tencent-hunyuan/hunyuanimage-3.0/llms.txt

Perform single image editing by providing a prompt and an input image path. Set `infer_align_image_size=True` to match the output resolution to the input.

```python
# --- Single image editing ---
cot_text, samples = model.generate_image(
    prompt="Turn the background into a snowy mountain landscape",
    image="./my_photo.jpg",            # path, PIL Image, or base64 string
    seed=7,
    image_size="auto",
    use_system_prompt="en_unified",
    bot_task="think_recaption",
    infer_align_image_size=True,       # output matches input resolution
    diff_infer_steps=50,
    verbose=2,
)
samples[0].save("edited.png")
```

--------------------------------

### vLLM HTTP Server

Source: https://context7.com/tencent-hunyuan/hunyuanimage-3.0/llms.txt

Deploy HunyuanImage-3.0 behind a vLLM-based OpenAI-compatible API server for high-throughput or production environments. This requires a custom vLLM branch.

```APIDOC
## vLLM HTTP Server — `vllm_infer/`

For high-throughput or production deployment, HunyuanImage-3.0 can be served behind a vLLM-based OpenAI-compatible API server. Requires a custom vLLM branch.

### Installation and Server Launch
```bash
# 1. Install custom vLLM
git clone --branch feature/hunyuan_image_3.0 https://github.com/kippergong/vllm.git
cd vllm && VLLM_USE_PRECOMPILED=1 pip install --editable . && cd ..

# 2. Launch the server (serves on http://localhost:8000)
export VLLM_ENABLE_HUNYUAN_IMAGE3_TASK="1"
sh vllm_infer/run_vllm_server.sh /path/to/HunyuanImage-3-model
# Equivalent manual command:
# vllm serve /path/to/model \
#   --trust-remote-code \
#   --served-model-name vllm_hunyuan_image3 \
#   --max-model-len 10000 \
#   --gpu-memory-utilization 0.6 \
#   --max-num-seqs 1 \
#   --enforce-eager \
#   -tp 8
```

### Generate Image via Python Client
```bash
# Generate an image via the Python client
python vllm_infer/openai_client.py \
    --prompt "A panda eating bamboo in a lush forest" \
    --width 1024 --height 1024 \
    --seed 42 \
    --bot-task image
# Saves output to output.png

# Custom size
python vllm_infer/openai_client.py \
    --prompt "Sunset over a calm ocean" \
    --width 1280 --height 768
```
```

--------------------------------

### Generate Image with Custom Size

Source: https://github.com/tencent-hunyuan/hunyuanimage-3.0/blob/main/vllm_infer/README.md

Generates an image with a custom width and height, overriding the default size.

```bash
python openai_client.py --width 1280 --height 768 --prompt "sunset beach"
```

--------------------------------

### Multi-Image Fusion with HunyuanImage

Source: https://context7.com/tencent-hunyuan/hunyuanimage-3.0/llms.txt

Combine multiple images (up to 3) by listing their paths in the `image` parameter. This enables creative fusion and style transfer.

```python
# --- Multi-image fusion (up to 3 inputs) ---
cot_text, samples = model.generate_image(
    prompt="Combine the logo from image 1 with the material style of image 2 to create a new sticker",
    image=["./logo.png", "./reference_material.png"],  # comma-separated list
    seed=43,
    image_size="auto",
    use_system_prompt="en_unified",
    bot_task="think_recaption",
    infer_align_image_size=True,
    diff_infer_steps=50,
)
samples[0].save("fused_sticker.png")
```

--------------------------------

### Taylor Cache Acceleration

Source: https://context7.com/tencent-hunyuan/hunyuanimage-3.0/llms.txt

Enable Taylor Cache for diffusion step-skipping optimization to reduce inference time by reusing cached model outputs. This can be done via CLI or Python API, with options to configure interval, order, and enhancement steps.

```APIDOC
## Taylor Cache Acceleration

Taylor Cache is a diffusion step-skipping optimization that reuses cached model outputs at regular intervals to reduce total forward passes. Enable it via CLI or Python API for faster inference (slight quality trade-off).

### CLI Example
```bash
python3 run_image_gen.py \
    --model-id ./HunyuanImage-3-Instruct \
    --prompt "A hyperrealistic portrait of an astronaut on Mars" \
    --bot-task think_recaption \
    --image-size "1024x1024" \
    --diff-infer-steps 50 \
    --use-taylor-cache \
    --taylor-cache-interval 5 \
    --taylor-cache-order 2 \
    --taylor-cache-enable-first-enhance \
    --taylor-cache-first-enhance-steps 3 \
    --taylor-cache-enable-tailing-enhance \
    --taylor-cache-tailing-enhance-steps 1 \
    --moe-impl flashinfer \
    --save ./taylor_cached_output.png
```

### Python API Example
```python
# Python API equivalent
cot_text, samples = model.generate_image(
    prompt="A hyperrealistic portrait of an astronaut on Mars",
    seed=1,
    image_size="1024x1024",
    bot_task="think_recaption",
    use_system_prompt="en_unified",
    diff_infer_steps=50,
    use_taylor_cache=True,
    taylor_cache_interval=5,
    taylor_cache_order=2,
    taylor_cache_enable_first_enhance=True,
    taylor_cache_first_enhance_steps=3,
    taylor_cache_enable_tailing_enhance=True,
    taylor_cache_tailing_enhance_steps=1,
    taylor_cache_low_freqs_order=2,
    taylor_cache_high_freqs_order=2,
)
samples[0].save("taylor_cached_output.png")
```
```

--------------------------------

### Configure FlowMatchDiscreteScheduler

Source: https://context7.com/tencent-hunyuan/hunyuanimage-3.0/llms.txt

Configure the internal diffusion scheduler for the HunyuanImage3Text2ImagePipeline. Supports Euler, Heun-2, midpoint-2, and Runge-Kutta-4 solvers. Use `set_timesteps` for inference and `step` for manual denoising. Ensure CUDA is available for device placement.

```python
from hunyuan_image_3.hunyuan_image_3_pipeline import FlowMatchDiscreteScheduler

# Default Euler scheduler
scheduler = FlowMatchDiscreteScheduler(
    num_train_timesteps=1000,
    shift=1.0,
    reverse=True,
    solver="euler",          # "euler", "heun-2", "midpoint-2", "kutta-4"
    use_flux_shift=False,
)

# Set timesteps for inference
scheduler.set_timesteps(num_inference_steps=50, device="cuda")
print("Timesteps:", scheduler.timesteps[:5])
# tensor([999., 979., 959., 939., 919.], device='cuda:0')

# Step through denoising manually (illustrative)
import torch
batch_size, channels, h, w = 1, 16, 64, 64
latents = torch.randn(batch_size, channels, h, w, device="cuda")
for t in scheduler.timesteps:
    model_output = torch.randn_like(latents)    # replace with real model output
    result = scheduler.step(model_output, t, latents)
    latents = result.prev_sample
```

--------------------------------

### Image-to-Image Editing with `model.generate_image`

Source: https://context7.com/tencent-hunyuan/hunyuanimage-3.0/llms.txt

Use the `generate_image` method to perform image editing and multi-image fusion. You can provide a single image or a list of images for various creative tasks.

```APIDOC
## Image-to-Image Editing — `model.generate_image` with `image`

Pass one or more reference images via the `image` parameter to enable the Instruct model's creative editing and multi-image fusion capabilities.

```python
from transformers import AutoModelForCausalLM

model_id = "./HunyuanImage-3-Instruct"
model = AutoModelForCausalLM.from_pretrained(
    model_id, trust_remote_code=True, torch_dtype="auto",
    device_map="auto", moe_impl="flashinfer", moe_drop_tokens=True,
)
model.load_tokenizer(model_id)

# --- Single image editing ---
cot_text, samples = model.generate_image(
    prompt="Turn the background into a snowy mountain landscape",
    image="./my_photo.jpg",            # path, PIL Image, or base64 string
    seed=7,
    image_size="auto",
    use_system_prompt="en_unified",
    bot_task="think_recaption",
    infer_align_image_size=True,       # output matches input resolution
    diff_infer_steps=50,
    verbose=2,
)
samples[0].save("edited.png")

# --- Multi-image fusion (up to 3 inputs) ---
cot_text, samples = model.generate_image(
    prompt="Combine the logo from image 1 with the material style of image 2 to create a new sticker",
    image=["./logo.png", "./reference_material.png"],  # comma-separated list
    seed=43,
    image_size="auto",
    use_system_prompt="en_unified",
    bot_task="think_recaption",
    infer_align_image_size=True,
    diff_infer_steps=50,
)
samples[0].save("fused_sticker.png")
```
```