Text-to-speech
Local synthesis with Vietnamese Northern, Southern and Central dialects and American and British English accents, returned as a WAV file.
Overview
Text-to-speech runs on the server through three engines: mlx-audio (VoxCPM2, Kokoro, OmniVoice), VietVoice-TTS (Vietnamese dialects) and Piper (instant, robotic fallback). Each accent ships as a separate female and male voice; pick the voice id to choose dialect, accent and gender.
Auth: key, approved session or trusted local network (require_user_or_local). Synthesis is synchronous and can be slow: the call holds the connection until the clip is rendered and it waits in the same single queue as chat and transcription. Keep clips short when calling through the public edge (100-second timeout).
Text-to-speech is not part of the OpenAI-compatible text adapter.
List voices
GET /api/ai/tts/voices
curl -s https://maximind.dev/api/ai/tts/voices -H "x-api-key: $MAXIMIND_API_KEY"
Credits: 0.
Voices
id |
Label | Engine | Dialect / accent | Gender | Notes |
|---|---|---|---|---|---|
vi-voxcpm |
Vietnamese — VoxCPM2 (premium) | mlx-audio | Vietnamese (neutral/Northern) | — | Default. Highest-quality Vietnamese. Honors speed. |
vi-vv-south-f |
Vietnamese — Southern female (VietVoice) | vietvoice | Southern | female | Honors speed. |
vi-vv-south-m |
Vietnamese — Southern male (VietVoice) | vietvoice | Southern | male | Honors speed. |
vi-vv-north-f |
Vietnamese — Northern female (VietVoice) | vietvoice | Northern | female | Honors speed. |
vi-vv-north-m |
Vietnamese — Northern male (VietVoice) | vietvoice | Northern | male | Honors speed. |
vi-vv-central-f |
Vietnamese — Central female (VietVoice) | vietvoice | Central | female | Honors speed. |
vi-vv-central-m |
Vietnamese — Central male (VietVoice) | vietvoice | Central | male | Honors speed. |
en-kokoro |
English — American female (Kokoro) | mlx-audio | American English | female | Kokoro af_heart. Lessons and shadowing. Honors speed. |
en-kokoro-us-m |
English — American male (Kokoro) | mlx-audio | American English | male | Kokoro am_michael. Honors speed. |
en-kokoro-uk-f |
English — British female (Kokoro) | mlx-audio | British English | female | Kokoro bf_emma. Honors speed. |
en-kokoro-uk-m |
English — British male (Kokoro) | mlx-audio | British English | male | Kokoro bm_george. Honors speed. |
multi-omnivoice |
Multilingual — OmniVoice | mlx-audio | Multilingual | — | drbaph/OmniVoice-bf16; multilingual and voice cloning. Honors speed. |
vi-piper |
Vietnamese — Piper (fast) | piper | Vietnamese (Northern) | female | vi_VN-vais1000-medium.onnx. Instant, robotic. Ignores speed. |
en-piper |
English — Piper (fast) | piper | American English | female | en_US-amy-medium.onnx. Instant, robotic. Ignores speed. |
VietVoice is higher quality but slower (roughly 1 to 2 s of audio per 10 s of compute). Have a native speaker spot-check the premium Vietnamese voice.
Synthesize
POST /api/ai/tts (application/json)
curl -X POST https://maximind.dev/api/ai/tts \
-H "x-api-key: $MAXIMIND_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text":"Xin chào các em","voice":"vi-voxcpm","speed":1.0}'
{"ok": true, "url": "/api/ai/tts/file/AbC123xy.wav"}
| Name | Type | Required | Description |
|---|---|---|---|
text |
string | Yes | Text to speak. Trimmed; empty returns HTTP 400 text is required. |
voice |
string | No | A voice id from the table. Default vi-voxcpm. An unknown id silently falls back to vi-piper. |
speed |
number | No | Default 1.0, clamped to 0.5 to 2.0; non-numeric becomes 1.0. Applied to mlx-audio and VietVoice voices; Piper ignores it. Only sent to the engine when it differs from 1.0 by more than 0.01. |
The response url is server-relative; prepend the hostname to download. The file name is random (token_urlsafe(8) plus .wav). Credits: 1.
Download the audio
GET /api/ai/tts/file/{name}
No auth: the random file name is the capability. Returns raw audio with Content-Type: audio/wav.
curl https://maximind.dev/api/ai/tts/file/AbC123xy.wav -o speech.wav
/ or .. in the name, or a missing file, returns 404.
Rate a voice
GET /api/ai/ratings and POST /api/ai/ratings
A 1 to 5 star rating with an optional note per model, shown in the AI Studio (/lab) dropdowns. Body: {"model_type":"chat"|"image"|"voice","model_id":"<id>","stars":0-5,"note":""}. stars at or below 0 with an empty note clears the rating. Credits: 0.
curl -X POST https://maximind.dev/api/ai/ratings -H "x-api-key: $MAXIMIND_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model_type":"voice","model_id":"vi-vv-south-f","stars":5,"note":"natural Southern"}'
Errors
| Status | Meaning |
|---|---|
| 400 | text is required. |
| 401 / 403 | Missing key, or pending account. |
| 404 | Audio file not found or invalid name. |
| 500 | tts failed: <reason> (engine error or timeout). |
Limits and costs
- Engine timeouts: Piper 180 s, mlx-audio 300 s, VietVoice 300 s. Through the public edge the request itself is cut at about 100 s, so long texts may time out at the edge before the engine finishes.
- One heavy task at a time server-wide; a TTS call may wait in the queue behind a transcription.
- Cost: 1 credit per clip (
tts), about $0.003 at the reference price. See Limits.