Quickstart
This guide gets you from nothing to a clip you can play: create an API key, send one request, and download the audio.
Get an API key
Sign in to Studio and open API keys. Give the key the name of the app that will use it and copy the value — it is shown once. Store it as a secret in your service, for example VOIXA_API_KEY.
A new key needs two to three minutes before the gateway accepts it. Until then every call answers {"message":"Forbidden"}. That is propagation, not a mistake in your request — wait and retry.
Check the API is up
/health needs no key, so it is the quickest way to confirm the base URL resolves.
cURL
curl https://api.voixa.vovix.io/v1/health
Response
{ "ok": true, "at": "2026-09-27T08:00:00.000Z" }
Make your first clip
Pick a voice — vi-truc-ly for Vietnamese, en-alba for English — and send text.
Request
curl -X POST https://api.voixa.vovix.io/v1/speak \
-H "x-api-key: $VOIXA_API_KEY" \
-H "content-type: application/json" \
-d '{ "voiceId": "vi-truc-ly", "text": "Xin chào, đây là Voixa." }'
Response
{
"clip": {
"clipId": "1c6765c8-3be4-44e0-85ae-57c71a07cb83",
"voiceId": "vi-truc-ly",
"voiceName": "Trúc Ly",
"language": "vi",
"text": "Xin chào, đây là Voixa.",
"chars": 23,
"source": "api",
"engine": "voixa-1",
"format": "wav",
"sampleRate": 48000,
"durationSec": 2.16,
"status": "ready",
"url": "https://…/library/…/1c6765c8-….wav?Signature=…"
}
}
url is a signed link to the WAV, valid for one hour. Ask for the clip again (GET /clips/{clipId}) whenever you need a fresh one.
If the clip comes back "status": "processing" — a long text, or an engine that had to start — poll GET /clips/{clipId} every second or two until it is ready. The SDK's say() does that for you.