---
license: apache-2.0
tags:
- ruslanmv
- avatar-renderer-mcp
- VideoGenie
---

# Avatar‑Renderer Checkpoints

This repository bundles all pretrained model checkpoints required by the [Avatar Renderer MCP](https://github.com/ruslanmv/avatar-renderer-mcp) pipeline.

**VideoGenie Avatar Generator** is a single‑image → talking‑head engine that ships an MCP‑native stdio server (`render_avatar` tool) and a FastAPI REST façade in one CUDA container. Drop it into any GPU pool and your MCP Gateway auto‑discovers it on boot.

This model‑hub repo allows you to fetch **all** necessary checkpoints from a **single source** via Git LFS or the Hugging Face Hub API.

---

## Directory structure

```
├── diff2lip
│   └── Diff2Lip.pth                # Audio‑to‑lip Diffusion model
├── fomm
│   └── vox-cpk.pth                 # First‑Order‑Motion vox‑cpk checkpoint
├── gfpgan
│   └── GFPGANv1.3.pth              # GFPGAN v1.3 face enhancement model
├── sadtalker
│   ├── SadTalker_V0.0.2_256.safetensors  # Safetensors release bundle
│   ├── epoch_20.pth               # Training checkpoint (epoch 20)
│   └── sadtalker.pth              # Legacy binary checkpoint
└── wav2lip
    └── wav2lip_gan.pth            # Wav2Lip GAN audio-to-lip model
```

Each subfolder contains one or more formats of the same model, ensuring compatibility with different inference pipelines.

---

## Usage

### 1. Clone via Git LFS

```bash
# Ensure Git LFS is installed:
#   https://git-lfs.github.com/

git clone https://huggingface.co/ruslanmv/avatar-renderer
cd avatar-renderer
# You'll now have a `models/` tree matching the structure above.
```

### 2. Download via Python (Hugging Face Hub API)

```python
from huggingface_hub import snapshot_download

# Download all files into ./models-cache
models_dir = snapshot_download(
    repo_id="ruslanmv/avatar-renderer",
    cache_dir="./models-cache",
)
print("Checkpoints downloaded to:", models_dir)
```

### 3. Integrate with Avatar Renderer MCP

In your **Avatar Renderer MCP** project, configure the checkpoint environment variables to point at the local `models` directory:

```bash
export FOMM_CKPT_DIR=/path/to/avatar-renderer/fomm
export DIFF2LIP_CKPT=/path/to/avatar-renderer/diff2lip/Diff2Lip.pth
export SADTALKER_CKPT_DIR=/path/to/avatar-renderer/sadtalker
export WAV2LIP_CKPT=/path/to/avatar-renderer/wav2lip/wav2lip_gan.pth
export GFPGAN_CKPT=/path/to/avatar-renderer/gfpgan/GFPGANv1.3.pth
```

Alternatively, mount the entire repo into `/models` inside a Docker container:

```dockerfile
FROM ruslanmv/avatar-renderer-mcp:latest
COPY --from=ruslanmv/avatar-renderer /models /models
CMD ["uvicorn", "app.api:app", "--host", "0.0.0.0", "--port", "8000"]
```

---

## License

This repository collects checkpoints that were released under their respective open licenses:

* **FOMM**: [Apache‑2.0](https://github.com/AliaksandrSiarohin/first-order-model/blob/master/LICENSE)
* **Diff2Lip**: [MIT](https://github.com/YuanGary/DiffusionLi/blob/main/LICENSE)
* **SadTalker**: [Apache‑2.0](https://github.com/Winfredy/SadTalker/blob/main/LICENSE)
* **Wav2Lip**: [MIT](https://github.com/Rudrabha/Wav2Lip/blob/master/LICENSE)
* **GFPGAN**: [MIT](https://github.com/TencentARC/GFPGAN/blob/main/LICENSE)

Please refer to each upstream project for full license details.

---

> Maintained by [ruslanmv](https://github.com/ruslanmv).
> Part of the [Avatar Renderer MCP](https://github.com/ruslanmv/avatar-renderer-mcp) ecosystem.