[Support] CosyVoice3-API - OpenAI-compatible Text-to-Speech API powered by CosyVoice 3

What it is

OpenAI-compatible Text-to-Speech API powered by CosyVoice 3 (Alibaba FunAudioLLM). State-of-the-art Chinese TTS with 18 dialects, 9 languages, built-in voices, instruction-based control, and zero-shot voice cloning. No bloat — just the model served via FastAPI.

Exposes /v1/audio/speech (OpenAI-compatible TTS), /v1/audio/speech/clone (voice cloning), /v1/voices, /docs (Swagger), /health

Template details

• App name: CosyVoice3-API

• Template URL: https://raw.githubusercontent.com/hsiang-han/unraid_templates/main/templates/cosyvoice3-api.xml

• Icon URL: https://raw.githubusercontent.com/hsiang-han/unraid_templates/main/assets/cosyvoice3-api-icon.png

• Project URL: https://github.com/hsiang-han/CosyVoice3-API

• Support URL: https://github.com/hsiang-han/CosyVoice3-API/issues

Container image strategy

• Repository (GPU only): ghcr.io/hsiang-han/cosyvoice3-api:latest

• Extra Parameters: --gpus all --shm-size=2g

• CUDA 12.8 — supports Blackwell (RTX 5060/5070/5090) and Ada GPUs

• Requires NVIDIA driver >= 570

Features

• Built-in voices: multiple Chinese/English/Japanese/Korean preset voices

• Instruction control: guide tone/emotion via text prompt

• Zero-shot voice cloning: clone any voice with just 3 seconds of reference audio

• FP16 inference: ~3-4GB VRAM (default), FP32: ~6-8GB VRAM

Default mappings / settings

• Port: 8080

• Host path: /mnt/user/appdata/cosyvoice3-api/models → /root/.cache/modelscope/hub

• API docs: http://[IP]:[PORT:8080]/docs

• First start downloads model (~2GB), subsequent starts are fast

Environment variables

• MODEL_DIR = FunAudioLLM/Fun-CosyVoice3-0.5B-2512 — ModelScope model ID

• FP16 = true — Half-precision inference, reduces VRAM by ~50%. Set to false only if you experience quality issues.

• PORT = 8080 — Internal API server port

• NVIDIA_VISIBLE_DEVICES = all — GPU selection

Usage

  # English TTS
  curl -X POST http://YOUR-UNRAID-IP:8080/v1/audio/speech \
    -F "input=Hello world, this is a test" \
    -F "voice=English Female" \
    --output english.wav

  # Chinese TTS
  curl -X POST http://YOUR-UNRAID-IP:8080/v1/audio/speech \
    -F "input=你好，世界" \
    -F "voice=中文女" \
    --output chinese.wav

  # Instruction control (English)
  curl -X POST http://YOUR-UNRAID-IP:8080/v1/audio/speech \
    -F "input=What a beautiful day" \
    -F "voice=English Female" \
    -F "instruct_text=Say it happily and energetically" \
    --output happy_en.wav

  # Instruction control (Chinese)
  curl -X POST http://YOUR-UNRAID-IP:8080/v1/audio/speech \
    -F "input=今天天气真好" \
    -F "voice=中文女" \
    -F "instruct_text=用开心的语气说" \
    --output happy_zh.wav

  # Voice cloning (3s reference audio)
  curl -X POST http://YOUR-UNRAID-IP:8080/v1/audio/speech/clone \
    -F "input=This is the cloned voice" \
    -F "prompt_text=Text spoken in the reference audio" \
    -F "[email protected]" \
    --output cloned.wav

  # List available voices
  curl http://YOUR-UNRAID-IP:8080/v1/voices

Works with any OpenAI-compatible TTS client.