chatterbox-tts-api — AI 语音合成工具中文文档

Install dependencies with uv (automatically creates venv)

uv sync

Install dependencies

pip install -r requirements.txt

Voice File Requirements

Supported Formats:

• MP3 (.mp3)
• WAV (.wav)
• FLAC (.flac)
• M4A (.m4a)
• OGG (.ogg)

Requirements:

• Maximum file size: 10MB
• Recommended duration: 10-30 seconds of clear speech
• Avoid background noise for best results
• Higher quality audio produces better voice cloning

Option 6: Try uv for better dependency resolution

uv sync uv run uvicorn app.main:app --host 0.0.0.0 --port 4123

**For local development**, install PyTorch with CUDA support:

Or with test dependencies (for contributors)

uv sync --group test

Local Installation with Python 🐍

Option A: Using uv (Recommended - Faster & Better Dependencies)

```bash

Install uv if you haven't already

curl -LsSf https://astral.sh/uv/install.sh | sh

Setup environment — using Python 3.11

python -m venv .venv source .venv/bin/activate

🐳 Docker (Recommended)

```bash

Clone and start with Docker Compose

git clone https://github.com/travisvn/chatterbox-tts-api cd chatterbox-tts-api

Use Docker-optimized environment variables

cp .env.example.docker .env # Docker-specific paths, ready to use

Choose your deployment method:

With Docker Compose Profiles

```bash

Same pattern works with all deployment variants:

docker compose -f docker/docker-compose.gpu.yml --profile frontend up -d # GPU + Frontend docker compose -f docker/docker-compose.uv.yml --profile frontend up -d # uv + Frontend docker compose -f docker/docker-compose.cpu.yml --profile frontend up -d # CPU + Frontend ```

Build for Production

Build the frontend for production deployment:

cd frontend && npm install && npm run build

You can then access it directly from your local file system at /dist/index.html.

For Docker deployment

cp .env.example.docker .env

Key environment variables (see the example files for full list):

| Variable                 | Default              | Description                    |
| ------------------------ | -------------------- | ------------------------------ |
| `PORT`                   | `4123`               | API server port                |
| `USE_MULTILINGUAL_MODEL` | `true`               | Enable 23-language support     |
| `EXAGGERATION`           | `0.5`                | Emotion intensity (0.25-2.0)   |
| `CFG_WEIGHT`             | `0.5`                | Pace control (0.0-1.0)         |
| `TEMPERATURE`            | `0.8`                | Sampling randomness (0.05-5.0) |
| `VOICE_SAMPLE_PATH`      | `./voice-sample.mp3` | Voice sample for cloning       |
| `DEVICE`                 | `auto`               | Device (auto/cuda/mps/cpu)     |

<details>
<summary><strong>🎭 Voice Cloning</strong></summary>

Replace the default voice sample:

Deploy

docker compose -f docker/docker-compose.yml up -d ```

Ensure NVIDIA Container Toolkit is installed

docker compose -f docker/docker-compose.gpu.yml up -d ```

</details>

<details> <summary><strong>📚 API Reference</strong></summary>

Option 1: Use default setup (now includes CUDA-enabled PyTorch)

docker compose -f docker/docker-compose.yml up -d

Option 2: Use explicit CUDA setup (traditional)

docker compose -f docker/docker-compose.gpu.yml up -d

Option 3: Use uv + GPU setup (recommended for GPU users)

docker compose -f docker/docker-compose.uv.gpu.yml up -d

Option 4: Use CPU-only setup (may have compatibility issues)

docker compose -f docker/docker-compose.cpu.yml up -d

Option 5: Clear model cache and retry with CUDA-enabled setup

docker volume rm chatterbox-tts-api_chatterbox-models docker compose -f docker/docker-compose.yml up -d --build

Check if uvicorn is installed

uvicorn --version

Full Stack mode with UI (using Docker)

python start.py fullstack

Install in development mode (pip)

pip install -e .

➡️ View the [Open WebUI docs for installing Chatterbox TTS API](https://docs.openwebui.com/tutorials/text-to-speech/chatterbox-tts-api-integration)

⚡️ Quick Start

git clone https://github.com/travisvn/chatterbox-tts-api
cd chatterbox-tts-api
uv sync
uv run main.py

[!TIP] uv installed with curl -LsSf https://astral.sh/uv/install.sh | sh

Or: cp .env.example .env # Local development paths, needs customization

API Usage

Quick Start

```bash

Quick Start

```bash

Basic Streaming Example

```python import requests

SSE Streaming Example (OpenAI Compatible)

```python import requests import json import base64

Quick Start Scripts

```bash

Add your voice sample (or use the provided one)

cp your-voice.mp3 voice-sample.mp3

Screenshots of Frontend (Web UI)

🖼️ View screenshot of full frontend web UI — light mode / dark mode

Replace the default voice sample

cp your-voice.mp3 voice-sample.mp3

Copy and customize environment variables

cp .env.example .env

Copy and customize environment variables

cp .env.example .env

Port Configuration

• API Only: Accessible at http://localhost:4123 (direct API access)
• With Frontend: Web UI at http://localhost:4321, API requests routed via proxy

The frontend uses a reverse proxy to route requests, so when running with --profile frontend, the web interface will be available at http://localhost:4321 while the API runs behind the proxy.

</details>

🎛️ Configuration

The project provides two environment example files:

• .env.example - For local development (uses ./models, ./voice-sample.mp3)
• .env.example.docker - For Docker deployment (uses /cache, /app/voice-sample.mp3)

Choose the appropriate one for your setup:

```bash

Create production environment

cp .env.example.docker .env nano .env # Set production values

Memory Configuration

Chatterbox TTS API

<p align="center"> <a href="https://github.com/travisvn/chatterbox-tts-api"> <img src="https://img.shields.io/github/stars/travisvn/chatterbox-tts-api?style=social" alt="GitHub stars"></a> <a href="https://github.com/travisvn/chatterbox-tts-api"> <img alt="GitHub forks" src="https://img.shields.io/github/forks/travisvn/chatterbox-tts-api"></a> <a href="https://github.com/travisvn/chatterbox-tts-api/issues"> <img src="https://img.shields.io/github/issues/travisvn/chatterbox-tts-api" alt="GitHub issues"></a> <img src="https://img.shields.io/github/last-commit/travisvn/chatterbox-tts-api?color=red" alt="GitHub last commit"> <a href="http://chatterboxtts.com/discord"> <img src="https://img.shields.io/badge/Discord-Voice_AI_%26_TTS_Tools-blue?logo=discord&logoColor=white" alt="Discord"> </a> </p>

FastAPI-powered REST API for Chatterbox TTS, providing OpenAI-compatible text-to-speech endpoints with voice cloning capabilities and additional features on top of the chatterbox-tts base package.

Start the API with FastAPI

uv run uvicorn app.main:app --host 0.0.0.0 --port 4123

Start the API with FastAPI

uvicorn app.main:app --host 0.0.0.0 --port 4123

API Only (default)

docker compose -f docker/docker-compose.yml up -d # Standard (pip-based) docker compose -f docker/docker-compose.uv.yml up -d # uv-optimized (faster builds) docker compose -f docker/docker-compose.gpu.yml up -d # Standard + GPU docker compose -f docker/docker-compose.uv.gpu.yml up -d # uv + GPU (recommended for GPU users) docker compose -f docker/docker-compose.cpu.yml up -d # CPU-only docker compose -f docker/docker-compose.blackwell.yml up -d # Blackwell (50XX) NVIDIA GPUs

API + Frontend (add --profile frontend to any of the above)

docker compose -f docker/docker-compose.yml --profile frontend up -d # Standard + Frontend docker compose -f docker/docker-compose.gpu.yml --profile frontend up -d # GPU + Frontend docker compose -f docker/docker-compose.uv.gpu.yml --profile frontend up -d # uv + GPU + Frontend docker compose -f docker/docker-compose.blackwell.yml --profile frontend up -d # (Blackwell) uv + GPU + Frontend

Test the API

curl -X POST http://localhost:4123/v1/audio/speech \ -H "Content-Type: application/json" \ -d '{"input": "Hello from Chatterbox TTS!"}' \ --output test.wav ```

<details> <summary><strong>🚀 Running with the Web UI (Full Stack)</strong></summary>

This project includes an optional React-based web UI. Use Docker Compose profiles to easily opt in or out of the frontend:

API only (default behavior)

docker compose -f docker/docker-compose.yml up -d

API + Frontend + Web UI (with --profile frontend)

docker compose -f docker/docker-compose.yml --profile frontend up -d

Start the API first (follow earlier instructions)

🚀 **[Complete Streaming Documentation →](docs/STREAMING_API.md)**

For comprehensive streaming features including:

• Advanced chunking strategies (sentence, paragraph, word, fixed)
• Quality presets (fast, balanced, high)
• Configurable parameters and performance tuning
• Real-time progress monitoring
• Python, JavaScript, and cURL examples
• Integration patterns for different use cases

Key Benefits:

• ⚡ Lower latency - Start hearing audio in 1-2 seconds
• 🎯 Better UX - No waiting for complete generation
• 💾 Memory efficient - Process chunks individually
• 🎛️ Configurable - Choose speed vs quality trade-offs

<details> <summary><strong>🐍 Python Examples</strong></summary>

Upload Endpoint (Default Voice)

import requests

response = requests.post(
    "http://localhost:4123/v1/audio/speech/upload",
    data={
        "input": "Hello world!",
        "exaggeration": 0.8
    }
)

with open("output.wav", "wb") as f:
    f.write(response.content)

API Endpoints

Parameters Reference

Memory Monitoring Endpoints

```bash

Get comprehensive API information

curl "http://localhost:4123/info"

**Status Response Example:**

See Status API Documentation for complete details.

Start with auto-reload (FastAPI development)

uvicorn app.main:app --host 0.0.0.0 --port 4123 --reload

Run API tests

python tests/test_api.py # or: uv run tests/test_api.py

Test specific endpoint

curl http://localhost:4123/health

Check API documentation

curl http://localhost:4123/openapi.json ```

FastAPI Development Features

• Auto-reload: Use --reload flag for development
• Interactive docs: Visit /docs for live API testing
• Type hints: Full IDE support with Pydantic models
• Validation: Automatic request/response validation
• Modular structure: Easy to extend and maintain

</details>

<details> <summary><strong>🤝 Contributing</strong></summary>

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Ensure FastAPI docs are updated
6. Submit a pull request

</details>

🔗 Integrations

Alternative startup method

python main.py ```

</details>

<details> <summary><strong>💻 Development</strong></summary>