Practical overview
When it fits
Use AvatarAI when a conversational experience needs a visible, speaking avatar and you can configure and operate the application’s AI, storage and deployment components.
Who it is for
- Developers prototyping avatar-based customer-support or reception interfaces.
- Teams creating virtual presenters or conversational kiosks.
- Builders who want to self-host and adapt a web application that joins speech, LLM and lip-sync components.
Documented uses
- Create an avatar from a face image for interactive conversations.
- Transcribe spoken input and generate an LLM response.
- Produce spoken replies with a selected voice and lip-synced video.
- Run a local development setup or configure the application for GPU/AWS deployment.
Requirements & limits
The repository identifies the project as open source under the MIT license and documents Docker-based and manual self-hosted development setups.
- Docker and Docker Compose v2+ are the recommended development prerequisites; manual setup instead lists Python 3.10+, Node.js 18+, FFmpeg, PostgreSQL and Redis.
- The documented frontend uses Next.js, React and TypeScript; the backend uses FastAPI, PostgreSQL, Redis and Celery.
- Claude, GPT-4o and local models through Ollama, vLLM or LM Studio are listed as LLM choices.
- The speech and video stack includes faster-whisper, Chatterbox Multilingual and MuseTalk V1.5; the repository also describes Edge TTS and gTTS fallback voices.
- MuseTalk model setup requires a roughly 9 GB download, and the repository describes GPU use for real-time video performance.
Check current requirements in the official documentation. Source-based guidance does not mean OpenViST has run or independently tested this project.
Start the Docker development setup
Bring up AvatarAI's development services with local upload storage.
Before you start
- Docker and Docker Compose v2 or later.
- An Anthropic API key or OpenAI API key for the configured LLM.
Steps
Clone the ai-avatar-system repository and change into its directory.
Copy .env.example to .env and add the Anthropic or OpenAI API key.
Run docker compose up -d.
Use the documented local frontend at port 3000, backend at port 8000, API documentation at port 8000/docs, or Celery Flower at port 5555.
Expected outcome
The Docker development services are started, with local storage enabled by default and uploads saved under backend/uploads/.
Guide limitations
- This is a development setup, not a production deployment guide.
- The guide does not configure the optional MuseTalk lip-sync models.
Enable MuseTalk lip-sync in the development setup
Configure the documented MuseTalk avatar engine after the development services are available.
Before you start
- A working AvatarAI development setup.
- About 9 GB for the one-time model download.
Steps
Run bash scripts/setup_musetalk.sh to download the models.
Set AVATAR_ENGINE=musetalk in .env.
Restart the backend with docker compose restart backend.
Expected outcome
The backend is configured to use MuseTalk for avatar lip-sync.
Guide limitations
- The repository says CPU MuseTalk is 30–50 times slower than GPU operation; real-time performance is associated with GPU deployment.
- This procedure covers configuration, not verification of a successful conversation.
Sources & review
Source record details
- Source availability
- Active
- Sources checked
- 15 October 2026
- Original website title
- PunithVT/ai-avatar-system · Official homepage title · retained in its source language