Qwen3-TTS-streaming/QUICKSTART_API.md

Qwen3-TTS API - Quick Start Guide

Get the API and Gradio demo running in minutes!

Prerequisites

• Python 3.9+
• CUDA 11.8+ (optional, for GPU acceleration)
• 8GB+ RAM (16GB+ recommended)

Installation

1. Clone and Install

# Navigate to the repository
cd Qwen3-TTS-streaming

# Install the package with API dependencies
pip install -e .
# Or just the API extras:
pip install -e ".[api]"

2. Start the API and Demo

Option A: Using the startup script (Recommended)

python start_api.py

Option B: Start services separately

Terminal 1 - Start API:

python -m api.main
# or
uvicorn api.main:app --host 0.0.0.0 --port 8000

Terminal 2 - Start Gradio Demo:

python -m api.gradio_demo

3. Access the Services

• Gradio Demo: http://localhost:7860
• API Server: http://localhost:8000
• API Documentation: http://localhost:8000/docs

Voice Cloning Setup (Optional)

To use voice cloning, place reference files in assets/voice_cloning/:

# Create reference files
mkdir -p assets/voice_cloning

# Copy or create your reference audio (must be WAV format)
cp your_voice.wav assets/voice_cloning/ref_audio.wav

# Create reference text file with the transcription
echo "Your reference text transcription here..." > assets/voice_cloning/ref_text.txt

The API will automatically load these files on startup.

First Test

Using the Gradio Demo (Easy)

1. Open http://localhost:7860 in your browser
2. Enter text to synthesize
3. Select language and options
4. Click "Generate Speech 🎵"

Using cURL (Command Line)

curl -X POST "http://localhost:8000/v1/audio/speech" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello, this is a test.",
    "language": "English"
  }'

Using Python

import requests
import base64
from io import BytesIO
import soundfile as sf

# Make request
response = requests.post(
    "http://localhost:8000/v1/audio/speech",
    json={
        "text": "Hello, world!",
        "language": "English"
    }
)

# Decode and save audio
data = response.json()
audio_bytes = base64.b64decode(data["audio_base64"])
audio, sr = sf.read(BytesIO(audio_bytes))
sf.write("output.wav", audio, sr)
print(f"✅ Saved audio: {data['duration']:.2f}s at {sr} Hz")

API Endpoints

Health & Models

GET /v1/health              # Check API status
GET /v1/models              # List available models

Text-to-Speech

POST /v1/audio/speech       # Generate audio
POST /v1/audio/speech/stream # Stream audio (real-time)

Streaming Audio

The streaming endpoint returns WAV frames with length prefixes for real-time audio:

import requests

response = requests.post(
    "http://localhost:8000/v1/audio/speech/stream",
    json={
        "text": "This is a streaming test.",
        "language": "English",
        "stream_options": {
            "emit_every_frames": 8,
            "decode_window_frames": 80,
            "overlap_samples": 512
        }
    },
    stream=True
)

# Process streaming chunks
for chunk in response.iter_content(chunk_size=65536):
    # Parse: [frame_length: 4 bytes][frame_data: frame_length bytes]
    frame_len = int.from_bytes(chunk[:4], byteorder='big')
    frame_data = chunk[4:4 + frame_len]
    # Play or process frame_data...

Voice Cloning Usage

Once reference files are in assets/voice_cloning/:

response = requests.post(
    "http://localhost:8000/v1/audio/speech",
    json={
        "text": "New text in cloned voice",
        "language": "English",
        "voice_clone_mode": "reference_audio"  # Enable voice cloning
    }
)

Supported Languages

• English
• Russian
• Chinese (Simplified)
• Japanese
• Korean
• Auto (automatic detection)

Performance Tips

GPU Usage

The API automatically uses CUDA if available:

• Monitor GPU: nvidia-smi
• Requires: CUDA 11.8+ and cuDNN

Faster Streaming

Adjust streaming options:

"stream_options": {
    "emit_every_frames": 4,      # Lower = faster first chunk
    "decode_window_frames": 40,  # Lower = faster, less quality
    "overlap_samples": 512
}

Lower Memory Usage

# Use CPU only
python start_api.py --device cpu

# Or manually in code (api/main.py):
model_state.device = "cpu"

Troubleshooting

API won't start

ModuleNotFoundError: No module named 'fastapi'
→ pip install fastapi uvicorn

GPU out of memory

CUDA out of memory
→ Use CPU: python start_api.py --device cpu
→ Or reduce batch size/model size

Voice cloning not working

→ Check files exist: assets/voice_cloning/ref_audio.wav
→ Check files exist: assets/voice_cloning/ref_text.txt
→ Ensure ref_text matches the audio content
→ Check API logs for error details

Slow first response

→ First request loads model (~30-60 seconds)
→ Subsequent requests are fast (2-5 seconds)
→ Streaming gives first chunk in ~1-2 seconds

Interactive Documentation

Visit http://localhost:8000/docs for:

• Swagger UI: Full API documentation with "Try it out"
• ReDoc: Alternative documentation view
• API schema: OpenAPI 3.0.2 specification

Next Steps

1. Integrate with your app

   • Use the Python client code above
   • Or use any HTTP client in your language

2. Deploy to production

   • Use Gunicorn: gunicorn -w 4 api.main:app
   • Or Docker (guidelines in main API README)

3. Customize the API

   • Edit api/models.py for request/response schemas
   • Edit api/main.py for endpoint logic
   • Add more models to api/models.py enum

More Information

• API Documentation: See api/README.md
• Voice Cloning Setup: See assets/voice_cloning/README.md
• Examples: Check examples/ directory

Support

For issues or questions:

1. Check logs in the terminal
2. Visit /docs endpoint for API details
3. Review the comprehensive api/README.md
4. Check assets/voice_cloning/README.md for voice cloning issues

---

Happy synthesizing! 🎵