README.md

---
title: HunyuanImage-3.0
emoji: 🎨
colorFrom: purple
colorTo: blue
sdk: gradio
sdk_version: 5.44.0
app_file: app.py
pinned: false
short_description: Text-to-Image generation using Tencent HunyuanImage-3.0
---

# 🎨 HunyuanImage-3.0 Text-to-Image with Inference API

This Space provides an interface for the **Tencent HunyuanImage-3.0** model using Hugging Face Inference API (paid from your account balance).

## ✅ What's New

- **Real image generation** using HF Inference API
- **n8n integration** via REST API endpoint
- **Base64 image output** for easy integration
- **Automatic token-based authentication**

## 🔧 Setup Instructions

### 1. Get Your HF Token
1. Go to [Hugging Face Settings > Access Tokens](https://huggingface.co/settings/tokens)
2. Create a new token with `write` permissions
3. Copy the token (starts with `hf_...`)

### 2. Set Your Token in Space
1. Go to [Settings](https://huggingface.co/spaces/Alae65/HunyuanImage-3/settings)
2. Find "Variables and secrets" section
3. Click "Replace" next to HF_TOKEN
4. Paste your actual token (replace the placeholder)
5. Click "Save"

### 3. Restart the Space
After setting the token, click "Restart space" in Settings.

## 📡 API Endpoint for n8n Integration

### Using the Gradio API

The Space provides a REST API that can be called from n8n using the HTTP Request node.

**Endpoint URL:**
```
https://alae65-hunyuanimage-3.hf.space/gradio_api/call/api_generate
```

### n8n HTTP Node Configuration

1. Add an **HTTP Request** node in n8n
2. Configure as follows:

**Method:** POST

**URL:**
```
https://alae65-hunyuanimage-3.hf.space/gradio_api/call/api_generate
```

**Body (JSON):**
```json
{
  "data": [
    "A serene mountain landscape with a crystal clear lake",
    42,
    50
  ]
}
```

**Parameters:**
- `data[0]` (string): Your image prompt
- `data[1]` (integer): Seed number (for reproducibility)
- `data[2]` (integer): Number of inference steps (10-100)

**Response Format:**
The API returns a JSON with:
```json
{
  "success": true,
  "image_base64": "iVBORw0KGgoAAAANSUhEUg...",
  "seed": 42,
  "status": "Success!",
  "prompt": "A serene mountain landscape..."
}
```

### Example n8n Workflow

1. **Trigger** → Webhook or Schedule
2. **HTTP Request** → Call HunyuanImage API
3. **Code** → Decode base64 image if needed
4. **Save or Send** → Store image or send via email/Slack

### Python Example

```python
import requests
import base64
from PIL import Image
from io import BytesIO

url = "https://alae65-hunyuanimage-3.hf.space/gradio_api/call/api_generate"

payload = {
    "data": [
        "A beautiful sunset over the ocean",
        42,
        50
    ]
}

response = requests.post(url, json=payload)
result = response.json()

if result.get("success"):
    # Decode base64 image
    image_data = base64.b64decode(result["image_base64"])
    image = Image.open(BytesIO(image_data))
    image.save("output.png")
    print("Image saved successfully!")
```

## 🎯 Features

- 🎯 Advanced prompt understanding
- 🖼️ Multiple resolution support
- 🎲 Seed control for reproducibility
- ⚙️ Configurable diffusion steps (10-100)
- 📝 Example prompts included
- 🔌 REST API for n8n and automation
- 📦 Base64 image encoding

## 💰 Pricing

This Space uses the **Hugging Face Inference API** which is billed based on usage:
- Cost is deducted from your HF account balance
- You mentioned having $9 credit available
- Check [Billing Settings](https://huggingface.co/settings/billing) for details

## 📚 Model Information

- **Model:** [tencent/HunyuanImage-3.0](https://huggingface.co/tencent/HunyuanImage-3.0)
- **Architecture:** Autoregressive MoE (64 experts)
- **Parameters:** 80B total, 13B active per token
- **License:** tencent-hunyuan-community
- **Paper:** [arXiv:2509.23951](https://arxiv.org/abs/2509.23951)

## 🔗 Links

- [Official Website](https://hunyuan.tencent.com/image)
- [GitHub Repository](https://github.com/Tencent-Hunyuan/HunyuanImage-3.0)
- [Technical Paper](https://arxiv.org/pdf/2509.23951)
- [Model Card](https://huggingface.co/tencent/HunyuanImage-3.0)

## 📝 Citation

```bibtex
@article{cao2025hunyuanimage,
  title={HunyuanImage 3.0 Technical Report},
  author={Cao, Siyu and Chen, Hangting and others},
  journal={arXiv preprint arXiv:2509.23951},
  year={2025}
}
```