Installation Guide

Getting Started with Z-Image Turbo

Z-Image Turbo is designed to be accessible and easy to set up. This guide will walk you through the installation process and help you start generating images quickly.

System Requirements

Before installing Z-Image Turbo, ensure your system meets the following requirements:

• GPU: Consumer-grade graphics card with at least 16GB VRAM (NVIDIA recommended)
• RAM: 16GB system RAM minimum, 32GB recommended
• Storage: At least 20GB free disk space for model weights
• Operating System: Linux, Windows 10/11, or macOS
• Python: Version 3.8 or higher

Installation Methods

Method 1: Using Hugging Face

The easiest way to get started with Z-Image Turbo is through Hugging Face. You can use the model directly through the Transformers library.

First, install the required dependencies:

pip install torch torchvision diffusers transformers accelerate

Then, you can load and use the model in your Python code:

from diffusers import DiffusionPipeline
import torch

# Load the Z-Image Turbo model
pipe = DiffusionPipeline.from_pretrained(
    "Tongyi-MAI/Z-Image-Turbo",
    torch_dtype=torch.float16
)
pipe = pipe.to("cuda")

# Generate an image
prompt = "A serene mountain landscape at sunset"
image = pipe(
    prompt,
    num_inference_steps=8,
    guidance_scale=3.0
).images[0]

# Save the generated image
image.save("output.png")

Method 2: Using ModelScope

If you prefer using ModelScope, you can install the model through their platform:

pip install modelscope

Then use the following code:

from modelscope.pipelines import pipeline
from modelscope.utils.constant import Tasks

# Initialize the pipeline
image_synthesis = pipeline(
    Tasks.text_to_image_synthesis,
    model='Tongyi-MAI/Z-Image-Turbo'
)

# Generate image
result = image_synthesis({
    'text': 'A serene mountain landscape at sunset'
})

Method 3: Clone from GitHub

For developers who want to explore the code or contribute, you can clone the repository:

git clone https://github.com/Tongyi-MAI/Z-Image.git
cd Z-Image
pip install -r requirements.txt

Configuration Options

Z-Image Turbo supports various configuration parameters to control the generation process:

Resolution Categories

The model supports multiple resolution options:

• 1024x1024 (1:1 - Square)
• 1280x720 (16:9 - Landscape)
• 720x1280 (9:16 - Portrait)
• Custom resolutions up to 2048 pixels

Generation Parameters

• Steps: Number of inference steps (recommended: 8 for optimal quality/speed balance)
• Time Shift: Controls the diffusion process timing (range: 1-10, default: 3)
• Seed: Random seed for reproducible results (use -1 for random)
• Guidance Scale: Controls how closely the output follows the prompt

Using Z-Image Turbo on Hugging Face Spaces

For quick experimentation without local installation, you can use the online demo:

1. Visit the Hugging Face Space for Z-Image Turbo
2. Enter your text prompt in the input field
3. Select your desired resolution category and specific resolution
4. Adjust the number of steps (8 recommended)
5. Set the time shift parameter (3 is default)
6. Click "Generate" to create your image

The online demo provides a user-friendly interface where you can:

• Test different prompts and settings
• Download generated images
• Experiment with various resolution options
• Use random or fixed seeds for generation

Advanced Usage

Batch Generation

You can generate multiple images in a batch:

prompts = [
    "A peaceful garden with cherry blossoms",
    "Modern architecture in an urban setting",
    "Abstract art with vibrant colors"
]

for i, prompt in enumerate(prompts):
    image = pipe(prompt, num_inference_steps=8).images[0]
    image.save(f"output_{i}.png")

Custom Resolution

To use custom resolutions:

image = pipe(
    prompt,
    height=1024,
    width=1024,
    num_inference_steps=8
).images[0]

Bilingual Text Rendering

Z-Image Turbo supports both English and Chinese prompts:

# English prompt
image_en = pipe("A traditional Chinese garden").images[0]

# Chinese prompt
image_zh = pipe("一个传统的中国园林").images[0]

Troubleshooting

Out of Memory Errors

If you encounter CUDA out of memory errors:

1. Reduce the resolution
2. Enable CPU offloading:

   pipe.enable_model_cpu_offload()
   

3. Use half precision (float16) instead of full precision

Slow Generation

To improve generation speed:

1. Ensure you're using GPU acceleration
2. Use the recommended 8 steps instead of higher values
3. Enable attention slicing for lower memory usage:

   pipe.enable_attention_slicing()
   

Installation Issues

If you face installation problems:

1. Ensure all dependencies are up to date
2. Check that your CUDA version is compatible with PyTorch
3. Try creating a fresh virtual environment
4. Consult the GitHub repository for known issues

Best Practices

1. Start with 8 steps: This provides the best balance between quality and speed
2. Use descriptive prompts: More detailed prompts generally produce better results
3. Experiment with time shift: Values between 2-4 work well for most cases
4. Set a seed for consistency: When you find a good result, note the seed for reproducibility
5. Monitor VRAM usage: Keep an eye on memory consumption, especially with higher resolutions

Community and Support

Join the Z-Image community to:

• Share your generated images
• Get help with installation and usage
• Contribute to the project
• Stay updated on new features and improvements

For more information, visit the official GitHub repository and documentation.

Next Steps

Now that you have Z-Image Turbo installed, you can:

• Try the online demo to familiarize yourself with the interface
• Experiment with different prompts and settings
• Explore the blog for tips and examples
• Join the community to share your creations

Happy generating!