Connect AngeVoice to a client

Do not hard-code model capabilities. Discover what the running service supports and build requests from that response.

Discover capabilities first

GET /v1/tts/capabilities
GET /v1/audio/voices?detail=true

The capabilities response reports formats, encodings and voices for the active model. Not every model supports cloning or compressed output.

HTTP synthesis

curl -X POST http://127.0.0.1:8100/v1/audio/speech \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"model":"kokoro","input":"Text to speak","voice":"zm_010","response_format":"wav"}' \
  --output speech.wav

Set response_encoding=base64 when a JSON response is required. Read the returned sample rate, channels and media type.

Upload reference audio for cloning

curl -X POST http://127.0.0.1:8100/api/tts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F model=moss \
  -F text="Reference voice cloning test." \
  -F voice=Junhao \
  -F prompt_audio=@reference.wav \
  -F response_format=wav \
  --output clone.wav

ZipVoice also needs prompt_text matching the reference audio.

WebSocket streaming

WS /ws/v1/tts

{
  "model": "kokoro",
  "text": "Streaming synthesis test.",
  "voice": "zm_010",
  "format": "pcm_s16le",
  "binary": false,
  "token": "YOUR_TOKEN"
}

PCM streams must be played with the returned sample rate. A reverse proxy must forward WebSocket Upgrade headers.

Common integration problems