VoxCPM FastAPI

OpenAI-compatible TTS wrapper for VoxCPM2, built for Pandrator-style workflows.

This repository is a sibling service to the XTTS wrapper, with a similar API shape and voice upload behavior.

Quick Start

# Windows
run.bat

# Linux / macOS
bash run.sh

# Force CPU
run.bat --cpu

The launcher uses Pixi, installs pinned runtime dependencies, and starts the API at:

• http://0.0.0.0:8020

Required Endpoints

• GET /health
• GET /v1/models
• POST /v1/audio/speech
• GET /v1/audio/voices

Compatibility aliases and fallbacks:

• GET /v1/voices (alias)
• POST /v1/audio/voices (voice upload)
• POST /v1/files (legacy upload fallback)
• GET /v1/files (legacy voice discovery fallback)
• DELETE /v1/voices/{voice_id} (optional cleanup)

Model Policy

GET /v1/models returns VoxCPM2 entries only:

• openbmb/VoxCPM2
• voxcpm2 (alias)

Speech requests can use either ID.

Speech API Notes

POST /v1/audio/speech accepts OpenAI-style fields:

• model
• input
• voice
• response_format
• speed
• instructions

And VoxCPM extension fields:

• voxcpm object (cfg_value, inference_timesteps, normalize, denoise, retry_badcase, etc.)
• mode (reference or hifi)
• prompt_text
• control (voice design prompt, prepended as (control)...)

Output Format

V1 supports wav only. Any other response_format returns a 4xx error.

Voice Upload Notes

Upload fields accepted for compatibility:

• files (multi-part list)
• audio_sample (single file)
• file (legacy single file)

Metadata fields:

• voice_id
• name
• purpose
• prompt_text
• mode

Voice data is stored under voices/<voice_id>/ with a meta.json file.

Runtime Defaults

• VOXCPM_DEVICE=auto
• VOXCPM_OPTIMIZE=false (safer default on Windows)
• VOXCPM_LOAD_DENOISER=false
• VOXCPM_DEFAULT_MODEL=openbmb/VoxCPM2
• Pixi Python environment pinned to 3.12.*
• GPU torch stack pinned to torch==2.7.1 and torchaudio==2.7.1

Optional FlashAttention (Windows)

FlashAttention wheel install is GPU-aware and community-wheel based:

• enabled by default for Windows CUDA runs (set VOXCPM_INSTALL_FLASH_ATTN=false or --skip-flash-attn to disable)
• Ada (sm_89, e.g. RTX 40xx) uses lldacing/flash-attention-windows-wheel
• Blackwell (sm_120+, e.g. RTX 50xx) uses mjun0812/flash-attention-prebuild-wheels
• unsupported GPU architectures continue with SDPA fallback
• Windows install is wheel-only; no local CUDA compilation step is required
• use --install-flash-attn to force a reinstall attempt
• use --require-flash-attn (or VOXCPM_REQUIRE_FLASH_ATTN=true) to fail startup when FlashAttention is missing/broken
• startup logs always print FlashAttention status: ... so active state is explicit

Advanced overrides:

• VOXCPM_FLASH_ATTN_WHEEL_URL (single override for all GPUs)
• VOXCPM_FLASH_ATTN_WHEEL_ADA
• VOXCPM_FLASH_ATTN_WHEEL_BLACKWELL

Community wheel credits:

• https://huggingface.co/lldacing/flash-attention-windows-wheel
• https://github.com/mjun0812/flash-attention-prebuild-wheels

Dev

bin\pixi run pytest