vits-simple-api: one Flask service in front of four text-to-speech model families

The Docker path installs more than it looks like

The recommended deployment for Linux is Docker, and the first step is a self executing installer script rather than a command you can read before running it:

bash -c "$(wget -O- https://raw.githubusercontent.com/Artrajz/vits-simple-api/main/vits-simple-api-installer-latest.sh)"

It prompts for the files to download and pulls the image. Default paths for configuration and model folders are `/usr/local/vits-simple-api/`, and the project image is `artrajz/vits-simple-api:latest`. Starting and updating are stock compose commands:

docker-compose up -d

The compose file tells you more about the runtime than the README does. It exposes port 23456, sets `LANG` to `C.UTF-8` and `TZ` to `Asia/Shanghai`, runs `python app.py`, and mounts `./data` for model data plus `./config.yaml`, `./logs` and `gunicorn_config.py`. It also mounts a pyopenjtalk dictionary directory and an `nltk_data` directory, which is the first sign that Japanese and English phonemisation are baked in rather than optional.

The image is built from `artrajz/pytorch:2.2.1-cpu-py3.10.11-ubuntu22.04`. The Dockerfile installs build tools plus espeak-ng and cmake from apt, then builds jemalloc 5.3.0 from source and points `LD_PRELOAD` at it, which is a lot of tuning for an API wrapper and a sign that memory behaviour under long synthesis jobs mattered to someone. The container default runs gunicorn against `app:app`, with the direct `python app.py` line left in the compose file for development.

Cloning and running from a Python 3.10 virtual environment

The virtual environment route is three commands. Clone the repository:

git clone https://github.com/Artrajz/vits-simple-api.git

Install the dependencies, where Python 3.10 is the recommended version:

pip install -r requirements.txt

Then start the service:

python app.py

The tree also holds `run.ps1` for PowerShell, `entrypoint.sh` for containers and `api_test.py` at the root for exercising the endpoints. There is a second README, `README_zh.md`, so documentation exists in both directions.

`requirements.txt` is where the real scope of the project shows up. The scientific core is `numpy==1.23.3`, `scipy`, `librosa`, `soundfile==0.12.1`, `numba` and `graiax-silkcoder`. The machine learning side is `torch>=2.2.1`, `onnx==1.12.0`, `audonnx==0.7.0`, `vector_quantize_pytorch==1.12.12`, `pytorch_lightning` and `torchmetrics`. The web side is `flask==2.2.3`, `flask_apscheduler`, `pydantic==2.3.0`, `werkzeug==2.3.6`, `flask_login`, `flask_wtf` and `flask-cors`, with gunicorn installed separately in the Dockerfile.

The language stack is the part that sets this project apart from a single-model inference script. Text conversion and phonemisation libraries cover Chinese, Japanese, Korean, English, Thai, Cantonese and Indic scripts, among them `pyopenjtalk-prebuilt`, `pypinyin`, `jamo`, `cn2an`, `inflect`, `eng_to_ipa`, `ko_pron`, `indic_transliteration`, `num_thai`, `opencc`, `mecab-python3`, `g2p_en`, `jaconv`, `pyjyutping`, `g2pk2` and `fugashi`. Installing that on a clean machine is not quick, and one Windows-only entry in the file points at a project-specific package index.

Automatic model loading since 0.6.6 and the manual escape hatch

Since version 0.6.6 the default behaviour is to load every model found in `data/models`, which the README frames as making things easier for beginners. To opt out, set `tts_config.auto_load` to `false` in the generated `config.yaml` and declare the models yourself.

The manual path is a YAML list where each entry pairs a config file with its weights:

tts_model_config:
  models_dir: models
  auto_load: false
  tts_models:
  - config_path: model1/config.json
    vits_path: model1/G_1000.pth
  - config_path: model2/config.json
    vits_path: model2/G_1000.pth

Paths may be absolute, and relative ones resolve from `data/models` in the project root. The same list holds GPT-SoVITS entries, where the weight keys are `vits_path` and `t2s_path` in place of `config_path` and `vits_path`.

Those key names are a migration trap worth naming. The v0.6.16 release notes state that `model_path` and `sovits_path` were renamed to `vits_path`, and `gpt_path` to `t2s_path`, with automatic loading unaffected. If you are upgrading a hand written config from an older release, that rename is why nothing loads. The README is also direct that the loading path itself changed after 0.6.6, so the configuration has to be redone. The browser admin panel is the other supported route for editing `tts_model_config.tts_modes`, since `flask_login` and `flask_wtf` are both dependencies.

What the endpoints look like and why emotion is a number

The demo URLs are the fastest way to understand the API surface, because they show the shape of a request without needing a client library:

https://artrajz-vits-simple-api.hf.space/voice/vits?text=Difficult the first time, easy the second.&id=4
https://artrajz-vits-simple-api.hf.space/voice/speakers

Synthesis takes a text parameter and a speaker `id`, and some families take an extra selector. Speaker identity is an integer index into the model's speaker list, and the second address above is the endpoint that enumerates what an instance exposes. The README warns that different IDs support different languages, which is the sort of detail that only surfaces after you send text in the wrong language and get something odd back.

The W2V2 route adds an `emotion` parameter, and the demo comments label 111 as excited and 2077 as whispered. Emotion here is a coordinate in a trained vector space rather than a named label, so the parameter is a number you read out of the model's own documentation rather than a word you choose. Voice conversion is supported alongside plain text-to-speech, and the feature list adds long text batch processing, customisable default parameters and GPU accelerated inference.

Language handling is automatic and bounded by the model rather than chosen by you. The feature list says the scope of language detection follows the model's cleaner, with support for a custom language range. That follows from the model zoo design: if a model was trained on Japanese, feeding it Chinese is not a configuration mistake you should be able to commit.

The model families behind one interface

The checked feature list is the reason this repository exists at all. Plain VITS text-to-speech and voice conversion are the base. HuBert-soft VITS is supported, as are `vits_chinese` and Bert-VITS2. The list then names W2V2 VITS alongside a dimensional emotion model, and GPT-SoVITS from the RVC-Boss project.

Those are separate upstream codebases with different weight formats and different inference entry points, and the tree mirrors that. `vits/`, `bert_vits2/`, `gpt_sovits/` and `module/` sit at the root as separate packages, with `manager/`, `utils/`, `tts_app/`, `config.py`, `contants.py` and `logger.py` holding the shared Flask layer. The project describes itself as an extension of Moegoe with additional features, which explains the shape: an existing single-model API with a model zoo bolted on top.

Multiple models load at once, which is exactly what the `tts_modes` list and the `auto_load` flag exist to serve. SSML support appears on the feature list marked as work in progress, so treat it as partial. Because the weight formats differ across families, you will end up reading whichever upstream project trained your model to work out which keys belong in the config.

Windows packages, hosted demos and what the README does not cover

Windows users get a one-click path: download a deployment package from the releases page, extract it and run `start.bat`. The README is candid about why that package is incomplete. Compression ratios plus a 2GB per file limit on GitHub releases mean optional dependency models are left out, and the program normally downloads them when loading a sound model. If a model loads and returns empty audio, a troubleshooting section covers fetching that dependency by hand. The newest release notes repeat the same advice and suggest trying the 7-zip archive.

Two hosted demos exist, a Hugging Face Space and a Colab notebook, plus a Compshare image offering free time on an RTX 4090 or an RTX 3080 Ti. Those are the cheapest way to hear the API before installing anything.

What is missing is worth naming. There is no documented authentication story for the API, no rate limiting, and no mention of request queuing when several clients synthesise at once, even though `flask_apscheduler` is a dependency. Auto-loading scans a directory at startup, so a large `data` folder means a slow boot. Licensing is AGPL-3.0, which is a deliberate choice for a network service and the thing to settle before you put this behind your own product. The repository is not archived, the last push is recorded as 2026-05-18 with 1,048 stars, 135 forks and 33 open issues, and the three most recent releases are v0.6.16 from 2025-02-03, v0.6.15 from 2025-01-25 and v0.6.14 from 2024-11-30.

Editorial conclusion

vits-simple-api earns its place by being the boring HTTP layer that researchers keep writing themselves: a route per model family, one speaker ID, automatic model discovery, and language detection chosen per model rather than by you. The cost is a wide dependency surface, since `requirements.txt` pulls in torch, onnx, transformers and a stack of grapheme-to-phoneme libraries for a dozen languages, and the project is AGPL-3.0 licensed, which matters if you ever wrap it in a service you do not publish. Model weights are not included and the Windows release package deliberately leaves some of them out. The repository is not archived with a last push of 2026-05-18 and 1,048 stars, and the newest listed release is v0.6.16 from 2025-02-03. Start by dropping a model folder into `data/models` and letting automatic loading do the work, since manual loading is now the opt-in path.

Frequently asked questions

Official sources

1. Artrajz/vits-simple-api on GitHub
2. Issues
3. License: AGPL-3.0
4. README
5. Releases