README.md

---

title: Avatar Generator
emoji: 👔
colorFrom: blue
colorTo: green
sdk: docker
sdk_version: "latest"
app_file: app.py
pinned: false
---


# Avatar Generator API

A streamlined, Diffusers-based implementation for generating avatar images using SDXL, ControlNet, and face conditioning.

## Overview

This application provides a direct alternative to ComfyUI for avatar generation, focusing on:

1. **Reliability**: Direct control over file paths and permissions
2. **Performance**: Optimized pipeline for faster generation
3. **Simplicity**: Clean FastAPI-based architecture
4. **Extensibility**: Easy to modify and enhance

## Features

- **Pose-controlled generation** using ControlNet
- **FastAPI endpoints** for image generation
- **Face conditioning** for consistent identity
- **Docker-based deployment** for Hugging Face Spaces
- **Proper path handling** to avoid permission issues

## API Usage

The application exposes a `/generate` endpoint that accepts:

- `prompt`: Text description of the desired image
- `name`: Person name (used for filename)
- `role`: Role/job (used for styling and filename)
- `pose_image`: Reference image for pose
- `shirt_image`: Reference image for clothing
- `face_image`: (Optional) Reference image for face identity
- `steps`: (Optional) Number of inference steps
- `guidance_scale`: (Optional) How strongly to weight the prompt
- `width` & `height`: (Optional) Output image dimensions
- `seed`: (Optional) For reproducible generations

## Models

The application uses:

- **SDXL Base**: `stabilityai/stable-diffusion-xl-base-1.0`
- **ControlNet**: `thibaud/controlnet-openpose-sdxl-1.0`
- **PuLID Models**: `Defter77/pulid-models`

## Environment Variables

The following environment variables can be set:

- `HF_TOKEN`: Hugging Face API token for private models
- `HF_HOME`, `HF_HUB_CACHE`, `TRANSFORMERS_CACHE`: Set to `/app/.cache` by default

## Development

To run locally:

```bash

# Build the Docker image

docker build -t avatar-generator .



# Run the container

docker run -p 7860:7860 avatar-generator

```

## Advantages Over ComfyUI

This implementation offers several benefits:

1. **Direct File Control**: Explicit handling of file paths and permissions
2. **Simplified Architecture**: No complex node graph to maintain
3. **Reliable Error Handling**: Proper error reporting and cleanup
4. **Flexible API**: Easy to integrate with other applications
5. **Optimized Resources**: More efficient memory usage

## Credits

Created by Defter77, based on the Hugging Face Diffusers library.