MeloTTS FastAPI Server

A Windows PowerShell-based FastAPI wrapper for running MeloTTS on a local machine or LAN.

This repository contains the wrapper code and helper scripts only. It does not include MeloTTS source code, model weights, Python environments, caches, logs, or generated audio.

Target Environment

• Windows 10/11
• PowerShell 7 or Windows PowerShell
• Python 3.10 or 3.11
• Git
• FFmpeg on PATH for non-WAV output formats
• NVIDIA GPU with a working PyTorch/CUDA install recommended

All examples use <INSTALL_ROOT> as a placeholder, for example:

<INSTALL_ROOT>\melotts-fastapi-server

Do not commit your personal install path, cloned MeloTTS source tree, model cache, Python environment, logs, or generated audio.

What This Provides

Endpoints:

GET  /health
POST /v1/audio/speech
POST /tts

The main endpoint is OpenAI-style:

POST /v1/audio/speech

Supported MeloTTS language codes:

EN, ES, FR, ZH, JP, KR

The server defaults to ZH. Other languages are lazy-loaded on first request and then kept in memory.

Setup

Clone this wrapper:

cd <INSTALL_ROOT>
git clone https://github.com/leoli-dev/melotts-fastapi-server.git
cd .\melotts-fastapi-server

Run setup:

.\setup.ps1

The setup script will:

• clone https://github.com/myshell-ai/MeloTTS.git into .\MeloTTS
• create .\envs\melotts
• install PyTorch, wrapper requirements, and MeloTTS
• use .\cache\hf as the Hugging Face cache at runtime
• download required NLTK resources
• remove the full unidic package after install and use unidic_lite

Use CPU-only PyTorch:

.\setup.ps1 -Cpu

Pass a specific Python executable:

.\setup.ps1 -Python "C:\Path\To\python.exe"

Skip pieces you already manage yourself:

.\setup.ps1 -SkipMeloTTSClone
.\setup.ps1 -SkipPythonEnv

Start and Stop

Start the API server on all network interfaces:

.\start-melotts-tts.ps1

Equivalent default:

.\start-melotts-tts.ps1 -HostName 0.0.0.0 -Port 5065

Start on localhost only:

.\start-melotts-tts.ps1 -HostName 127.0.0.1 -Port 5065

Force CPU:

.\start-melotts-tts.ps1 -Cpu

Stop the service:

.\stop-melotts-tts.ps1

Health Check

Invoke-RestMethod http://127.0.0.1:5065/health

Example response:

{
  "ok": true,
  "device": "cuda",
  "supported_languages": ["EN", "ES", "FR", "ZH", "JP", "KR"],
  "default_language": "ZH",
  "loaded_languages": ["ZH"],
  "speakers": {
    "ZH": {
      "ZH": 1
    }
  },
  "requests": 0
}

API Example

PowerShell:

$body = @{
  input = "你好，这是 MeloTTS 普通话服务测试。"
  response_format = "wav"
  speed = 1.0
} | ConvertTo-Json

Invoke-WebRequest `
  -Uri "http://127.0.0.1:5065/v1/audio/speech" `
  -Method Post `
  -ContentType "application/json; charset=utf-8" `
  -Body $body `
  -OutFile ".\outputs\melotts-demo.wav"

Client script:

.\api-call-example.ps1 `
  -Text "你好，呢段声音係经由内网 API 生成。" `
  -OutFile ".\outputs\melotts-demo.wav"

See API_USAGE.md for full request fields, response headers, language examples, and troubleshooting.

Request Fields

• input: required text to synthesize
• response_format: wav, mp3, flac, ogg, or m4a
• speed: speech speed, greater than 0.2 and at most 3.0
• language: EN, ES, FR, ZH, JP, or KR
• speaker: optional speaker key for the selected language
• voice: optional OpenAI-style alias, also matched against speaker keys
• seed: optional torch seed, where 0 means no explicit seed

Successful responses include:

X-Audio-Duration
X-TTS-Elapsed
X-TTS-RTF
X-TTS-Chars-Per-Sec
X-TTS-Request-Count
X-TTS-Device
X-TTS-Language

Runtime Files

The scripts create these local-only directories:

MeloTTS\         cloned upstream MeloTTS source
envs\melotts\   Python virtual environment
cache\hf\       Hugging Face model cache
outputs\        generated test audio
run\            PID and logs
tmp\            temporary synthesis files

These paths are ignored by git.

Troubleshooting

Check MeloTTS import:

.\envs\melotts\Scripts\python.exe -c "from melo.api import TTS; print('melo ok')"

Check CUDA:

.\envs\melotts\Scripts\python.exe -c "import torch; print(torch.__version__); print(torch.version.cuda); print(torch.cuda.is_available())"

Check FFmpeg:

ffmpeg -version

If LAN clients cannot connect, confirm the service is listening on all interfaces:

Get-NetTCPConnection -LocalPort 5065 -State Listen

If the server works locally but another machine cannot connect, allow inbound traffic from an Administrator PowerShell:

New-NetFirewallRule `
  -DisplayName "MeloTTS FastAPI 5065" `
  -Direction Inbound `
  -Action Allow `
  -Protocol TCP `
  -LocalPort 5065 `
  -Profile Any

Third-Party Notice

This wrapper uses MeloTTS by MyShell and related model artifacts from Hugging Face, but does not redistribute them. See ATTRIBUTION.md.

The wrapper code and scripts in this repository are MIT licensed. Third-party projects, dependencies, and model artifacts remain under their own licenses.