Read this in other languages: English, 中文.

[TOC]

OddTTS - Multi-Engine TTS Speech Synthesis API Server (Compatible with OpenAI TTS API)

OddTTS is a powerful multi-engine text-to-speech synthesis service that provides a unified API interface and a user-friendly Web UI. With a single set of APIs, it supports multiple mainstream TTS engines, including EdgeTTS, Kokoro-82M-v1.1-zh, ChatTTS, Bert-VITS2, GptSovits v2, Moss-TTS-Nano, Audio8, etc., and also supports OpenAI TTS API calls.

v2.0 Highlight: Voice Cloning — Upload a 3-10 second reference audio to clone any voice, then use it like a built-in voice via API or Web UI.

Notes:

• Model files will be downloaded automatically on the first run.
• Model file sizes:
  • Kokoro-82M-v1.1-zh model: ~376MB.
  • EdgeTTS model: 0MB, no download required.
  • ChatTTS model: 2.4GB (FP16 precision).
  • Bert-VITS2 model: ~2GB (backbone + BERT feature network; each additional language requires ~1.3GB more).
  • GptSovits v2 model: ~2.5GB.
  • Moss-TTS-Nano 0.1B ONNX: ~200MB (pure CPU, ~20 languages).
  • Audio8 0.1B ONNX INT8: ~150MB (pure CPU, 11 languages).
  • Audio8 0.6B ONNX INT4: ~400MB (pure CPU, 11 languages).
• VRAM requirements:
  • EdgeTTS model: 0MB.
  • Kokoro-82M-v1.1-zh model: 0MB (runs on ordinary CPU).
  • Moss-TTS-Nano / Audio8 models: 0MB (pure CPU).
  • ChatTTS model: at least 2.5GB.
  • Bert-VITS2 model: at least 5GB. For few-shot fine-tuning, a GPU with 24GB+ VRAM is recommended.
  • GptSovits v2 model: at least 8GB. For few-shot fine-tuning, a GPU with 24GB/48GB+ VRAM is recommended.
• Users in China are recommended to use a mirror to accelerate model downloads.
  • Windows: set HF_ENDPOINT=https://hf-mirror.com
  • Linux/MacOS: export HF_ENDPOINT=https://hf-mirror.com
• Model files are large; it is recommended to run in an environment with sufficient disk space, or customize the model path (change models/hf_home to your own path).
  • Windows: set HF_HOME=x:/models/hf_home
  • Linux/MacOS: export HF_HOME=/models/hf_home

I. Introduction

1. About OddTTS

Because the Xiaoluo Tongxue project I am working on requires TTS speech synthesis functionality, and due to the hardware limitations of Xiaoluo Tongxue (an Alibaba Cloud ECS server at 99 CNY/year), EdgeTTS was the only option at first. However, my own computer has slightly better specs, so I tried several different TTS engines. I needed to create a unified wrapper for these TTS models so that Xiaoluo Tongxue could switch between different TTS engines at any time, and thus OddTTS was born.

Considering the wide range of uses for TTS functionality, I separated it out and open-sourced it. I hope it will be helpful to those who need TTS.

Note: If you want to use TTS engines other than EdgeTTS, you need to install the corresponding TTS engine yourself before installing and using OddTTS.

2. Why Choose OddTTS?

• Multi-Engine Support: Integrates EdgeTTS, Kokoro, ChatTTS, Bert-VITS2, GptSovits, Moss-TTS-Nano, Audio8, and other TTS engines.
• Voice Cloning: Upload a reference audio to clone any voice, usable via API and Web UI (v2.0+).
• Multiple Calling Methods: Supports file path return, Base64 encoding return, streaming response, and other output methods.
• User-Friendly Web UI: Provides a visual operation interface with voice cloning management panel.
• RESTful API: Provides a complete REST API for easy integration into other systems, including OpenAI-compatible endpoints.
• Highly Configurable: Supports GPU acceleration, concurrent thread adjustment, model preloading, and other configuration options.
• Cross-Platform Compatibility: Developed based on Python, supports Windows, Linux, macOS, and other operating systems.

3. Recommended Hardware

Xiaoluo Tongxue Usage

• Demo version: Alibaba Cloud ECS at 99 CNY/year (2 cores, 2GB), cannot run any TTS model locally, so EdgeTTS is used.
• Local version: My own computer is a ten-year-old laptop, using the Kokoro-82M-v1.1-zh model, running purely on CPU and offline, with fast execution speed.

II. Quick Start

1. Install OddTTS

pip install -i https://pypi.org/simple/ oddtts

2. Start OddTTS

1) Start with Default Configuration

Simply run the following command in your installed virtual environment to start:

oddtts

After startup, OddTTS will bind to 127.0.0.1 (local access only) by default, on port 9001. Access it in your browser at: http://localhost:9001

2) Start with Custom Configuration

To allow access from other IPs, start the service with the following command, setting the host to 0.0.0.0; the port can also be customized.

oddtts --host 0.0.0.0 --port 8080

III. OddTTS API Documentation

1. API Interface List

1) OpenAI API Compatible Interface

GET /v1/audio/speech

• Function: OpenAI TTS API compatible interface, details see OpenAI TTS API.
• Return: mp3 audio data.

2) Get Voice List

GET /v1/audio/voice/list

• Function: Get all voices supported by the current TTS engine.
• Return: Voice list, each voice contains name, language, gender, and other information.

3) Get Specific Voice Details

GET /v1/audio/voice/list/{voice_name}

• Function: Get detailed information for a specified voice.
• Parameter: voice_name - voice name.
• Return: Detailed voice information.

4) Generate TTS Audio (Return File Path)

POST /api/oddtts/file

• Function: Generate TTS audio and return the file path.
• Request Body:

  {
    "text": "Text to be converted to speech",
    "voice": "Voice name",
    "rate": Speech rate adjustment (-50 to 50),
    "volume": Volume adjustment (-50 to 50),
    "pitch": Pitch adjustment (-50 to 50)
  }

• Return: {"status": "success", "file_path": "Audio file path", "format": "mp3"}

5) Generate TTS Audio (Return Base64)

POST /api/oddtts/base64

• Function: Generate TTS audio and return Base64 encoding.
• Request Body: Same as file path API.
• Return: {"status": "success", "base64": "Base64 encoded audio data", "format": "mp3"}

6) Generate TTS Audio (Streaming Response)

POST /api/oddtts/stream

• Function: Generate TTS audio and return it as a streaming response.
• Request Body: Same as file path API.
• Return: Streaming audio data (audio/mpeg format).

7) Health Check

GET /oddtts/health

• Function: Check if the service is running normally.
• Return: {"status": "healthy", "message": "API service is running normally"}

8) Voice Cloning - Upload & Register Voice

POST /api/voice/clone

• Function: Upload a reference audio file and register it as a custom voice.
• Content-Type: multipart/form-data
• Form Fields:
  • audio_file — Reference audio file (wav/mp3/flac, recommended 3-10 seconds)
  • name — Voice identifier (e.g., xiaoming)
  • display_name — Display name (e.g., 小明)
  • engine — Target engine (default: moss_nano)
  • locale — Language (default: zh-CN)
• Return: Voice information JSON on success.

9) Voice Cloning - List Cloned Voices

GET /api/voice/clone/list

• Function: List all custom cloned voices.
• Query Parameter: engine (optional) — Filter by engine name.
• Return: Array of cloned voice objects.

10) Voice Cloning - Delete Cloned Voice

DELETE /api/voice/clone/<engine>/<voice_id>

• Function: Delete a cloned voice and its reference audio.
• Return: Success/failure JSON.

11) Voice Cloning - Preview Reference Audio

GET /api/voice/clone/audio/<engine>/<voice_id>

• Function: Play/download the reference audio of a cloned voice.
• Return: Audio binary stream (WAV format).

Note: Cloned voices are automatically merged into the voice list (/v1/audio/voice/list). You can use them directly in the OpenAI-compatible API by passing the voice identifier as the voice parameter.

2. API Call Examples

Here are some examples of calling the OddTTS API.

The voice parameter needs to be obtained from the backend voice list first, then filled in with the voice name supported by the current model (interface: /v1/audio/voice/list). The voice options differ for different models.

1) Call API using curl

curl.exe -X POST http://localhost:9001/api/oddtts/file ^
  -H "Content-Type: application/json" ^
  -d "{\"text\": \"Welcome to follow my WeChat official account: Aodeyuan. Let's learn AI together and keep up with the times!\", \"voice\": \"zm_011\", \"rate\": 0, \"volume\": 0, \"pitch\": 0}"

2) Call API using the OpenAI library

from openai import OpenAI

base_url = "http://localhost:9001/v1"
model = "oddtts-1"
api_key = "dummy"
voice = "zm_011"

text = "Welcome to follow my WeChat official account: Aodeyuan. Let's learn AI together and keep up with the times! Good good study, day day up!"

def test_openai_tts_api(voice_id):
    client = OpenAI(
        api_key=api_key,
        base_url=base_url
    )

    response = client.audio.speech.create(
        model=model,
        input=text,
        voice=voice_id,
        response_format="mp3"
    )
    response.write_to_file("output.mp3")

if __name__ == "__main__":
    test_openai_tts_api(voice)

3) Call API using the requests library

import requests

# Configure API base URL
API_BASE_URL = "http://localhost:9001"

# Test text
TEST_TEXT = "Welcome to follow my WeChat official account: Aodeyuan. Let's learn AI together and keep up with the times! Good good study, day day up!"

# Get voice list
def test_api_voices():
    response = requests.get(f"{API_BASE_URL}/v1/audio/voice/list")
    voices = response.json()
    print(f"Successfully retrieved {len(voices)} voice options")
    return voices

# Test generating TTS audio
def test_api_tts_file(voice_name):
    payload = {
        "text": TEST_TEXT,
        "voice": voice_name,
        "rate": 0,
        "volume": 0,
        "pitch": 0
    }
    response = requests.post(f"{API_BASE_URL}/api/oddtts/file", json=payload)
    result = response.json()
    print(f"Audio file path: {result.get('file_path')}")

4) Call API using JavaScript

async function generateTTS(text, voice) {
    const response = await fetch('http://localhost:9001/api/oddtts/file', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            text: text,
            voice: voice,
            rate: 0,
            volume: 0,
            pitch: 0
        })
    });
    const result = await response.json();
    console.log('Audio file path:', result.file_path);
    return result;
}

generateTTS('Welcome to follow my WeChat official account: Aodeyuan. Let\'s learn AI together and keep up with the times!', 'zm_011');

5) Voice Cloning Example (curl)

# Upload reference audio and register a cloned voice
curl -X POST http://localhost:9001/api/voice/clone \
  -F "audio_file=@reference.wav" \
  -F "name=xiaoming" \
  -F "display_name=小明" \
  -F "engine=moss_nano"

# Use the cloned voice via OpenAI-compatible API
curl -X POST http://localhost:9001/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d "{\"input\": \"你好，这是克隆音色测试\", \"voice\": \"xiaoming\"}" \
  --output cloned_speech.mp3

IV. Web Interface Usage

After the service starts, you can open the Web UI by visiting http://localhost:9001/ in your browser. It supports the following features:

• Text input area: Enter the text to be converted to speech.
• Voice selection: Choose different voices and languages (including cloned voices marked with 🎤).
• Parameter adjustment: Adjust speech rate, volume, pitch, and other parameters.
• Audio generation: Click the button to generate and play speech.
• Audio download: Download the generated audio file.
• Voice Cloning Panel: Upload reference audio, manage cloned voices, preview and delete.

V. Frequently Asked Questions

1. Service startup failure

   • Check if the port is occupied.
   • Confirm that all dependency packages are installed correctly.
   • Check the log file for detailed error information.

2. Speech synthesis failure

   • Check if the TTS engine configuration is correct.
   • Confirm that the selected voice exists in the current TTS engine.
   • For some engines that require internet access, confirm that the network connection is normal (e.g., EdgeTTS).

3. How to switch TTS engines

   • Modify the tts_type configuration item in the oddtts_config.py file.
   • Restart the service for the configuration to take effect.

4. Output format

   • The default output format is mp3.
   • Other formats such as wav, mp3, etc., can be specified via the response_format parameter.

VI. License

MIT License - see LICENSE file for details. Commercial use, personal use, feel free to use it however you like.

Questions and improvement suggestions are also welcome!