Documentation
See the production architectureOpen →Voice Stack turns text into natural speech in English and Arabic (Emirati, Saudi and Standard), with studio-grade voices, instant voice cloning and realtime streaming. Use the web studio, or call the HTTP / WebSocket API from your own product.
Overview
A browser workspace: write, pick a voice, listen, download. History is saved to your account.
POST text, get a 24 kHz WAV — or stream it over HTTP / WebSocket with first audio in ~0.4 s.
Browse the shared library or clone your own from a 3–10 s clip plus its transcript.
Quick start
Three steps to your first clip from the command line.
- 1Get an API key from your Xpin AI admin (keys are issued per workspace).
- 2Send text to
/v1/tts. - 3Play or save the WAV.
curl -X POST https://voice-api.xpin.ae/v1/tts \
-H "Authorization: Bearer $VOICE_STACK_KEY" \
-H "Content-Type: application/json" \
-d '{"text": "Welcome to Voice Stack.", "language": "en"}' \
-o welcome.wavText to Speech
Open Playground → Text to Speech. Type or paste up to 5,000 characters, pick a voice and a language, then press Generate speech.
| Control | What it does |
|---|---|
| Voice | Any library voice or one of your clones. Cloned voices reproduce the reference speaker; catalogue voices are designed from gender / age / accent. |
| Model | Realtime streams audio while later sentences are still rendering (best for previews). Studio renders the whole file first (best for long scripts and downloads). |
| Language | English or Arabic (Emirati). Arabic text is written right-to-left automatically; the quick-start chips set the language for you. |
| Speed | 50–150 %. 100 % is the natural pace of the voice. |
| Stability / Similarity / Style | Delivery hints for designed voices. Cloned voices follow the reference recording. |
Voice Library & cloning
Voices lists every shared voice with a one-click preview. Filter by language, accent or category, and save favourites to My Voices.
To clone a voice choose Create Voice and upload a clean 3–10 second clip of one speaker with its exact transcript. The clone is ready instantly and is private to your account. Good references: no music, no background voices, natural speech in the language you will generate.
History & downloads
Every generation is stored with your account and listed under History on the Text to Speech page — it survives refreshes and works on any device you sign in from. Each item can be replayed, downloaded as WAV, re-loaded into the editor or deleted.
Speech to Text
Playground → Speech to Text transcribes uploaded audio or video — drop a file (or record straight from your microphone), pick the spoken language and press Transcribe. English and Arabic are supported. Results come back with word-level timestamps: click any word to jump the player there, and export the transcript as plain text, .srt or .vtt subtitles. Transcripts are kept under History with their source audio, so you can reopen and replay them later.
Base URL & authentication
https://voice-api.xpin.ae
Every /v1/* route requires your API key. Send it as a bearer token or an X-API-Key header. WebSocket clients that cannot set headers may pass ?api_key= in the URL.
Authorization: Bearer <key> # or X-API-Key: <key>
GET /health is open and returns readiness, device, sample rate and the registered voice ids. A human-readable version with all components and machines lives at voice.xpin.ae/status (JSON: /api/status).
POST /v1/tts — full render
JSON in, one complete WAV out (24 kHz, 16-bit mono PCM). Long text is chunked internally; you always receive a single finished file. The response carries X-Duration-Seconds.
const res = await fetch("https://voice-api.xpin.ae/v1/tts", {
method: "POST",
headers: { "Authorization": "Bearer " + KEY, "Content-Type": "application/json" },
body: JSON.stringify({ text: "مرحباً، أهلاً بك في فويس ستاك", language: "afb", voice_id: "v_…" }),
});
const wav = await res.arrayBuffer(); // audio/wavimport requests
r = requests.post("https://voice-api.xpin.ae/v1/tts",
headers={"Authorization": f"Bearer {KEY}"},
json={"text": "Hello from Voice Stack.", "language": "en", "speed": 1.0})
r.raise_for_status()
open("out.wav", "wb").write(r.content)POST /v1/tts/stream — HTTP streaming
Same body, but the WAV is streamed in chunks as each sentence is synthesized, so playback can start after the first chunk. The WAV header uses live-stream placeholder sizes; players read to end of stream. Use chunk_chars to tune chunk length.
curl -N -X POST https://voice-api.xpin.ae/v1/tts/stream \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"text": "First sentence plays while the rest still renders.", "chunk_chars": 200}' \
| ffplay -autoexit -nodisp -i -<audio> element. Safari and Firefox need the full response first — fetch it, rewrite the RIFF/data sizes, and play from a Blob (the studio does this for you).WS /v1/tts/ws — WebSocket streaming
Send one JSON text frame with the same fields as /v1/tts; receive a start frame, raw PCM binary frames, then an end frame.
| Frame | Payload |
|---|---|
| → text | {"text": "...", "voice_id": "v_…", "language": "en"} |
| ← start | {"type":"start","sample_rate":24000,"format":"pcm_s16le","channels":1} |
| ← binary ×N | Raw 16-bit little-endian PCM, one frame per text chunk |
| ← end | {"type":"end","chunks":N,"duration_s":…} |
| ← error | {"type":"error","message":"…"} |
const ws = new WebSocket("wss://voice-api.xpin.ae/v1/tts/ws?api_key=" + KEY);
ws.binaryType = "arraybuffer";
ws.onopen = () => ws.send(JSON.stringify({ text: "Realtime speech for agents.", language: "en" }));
ws.onmessage = (e) => {
if (typeof e.data === "string") { const m = JSON.parse(e.data); if (m.type === "end") ws.close(); return; }
playPcm16(new Int16Array(e.data), 24000); // your AudioContext player
};POST /v1/voices — register a voice
Multipart upload of ref_audio (3–10 s of one speaker) and ref_text (its exact transcript). Returns a content-addressed voice_id — the same clip and transcript always yield the same id — usable in any TTS request.
curl -X POST https://voice-api.xpin.ae/v1/voices \
-H "Authorization: Bearer $KEY" \
-F "ref_audio=@reference.wav" \
-F "ref_text=Exact transcript of the reference audio."
# → {"voice_id": "v_b38cd8b25298abbc", "ref_text": "..."}Request fields
| Field | Type | Default | Notes |
|---|---|---|---|
| text | string | required | Up to 20,000 characters. |
| voice_id | string | "default" | Id returned by /v1/voices. Omit for the default voice. |
| language | string | auto | en, afb (Emirati), arb (Standard Arabic) — see Languages. |
| instruct | string | — | Voice-design attributes; overrides voice_id. See Voice design. |
| speed | number | 1.0 | 0.25 < speed < 4.0. >1 faster, <1 slower. |
| normalize_text | boolean | false | Speak numbers, dates and currency as words. |
| chunk_chars | integer | 200 | Streaming only: target characters per chunk (20–1000). |
Languages
Pass either the ISO 639-3 code or the lowercase English name. Voice Stack currently offers:
| Code | Language | Notes |
|---|---|---|
| en | English | All accents; catalogue voices default to American. |
| afb | Arabic — Emirati / Gulf | Use for Emirati and Saudi Gulf speech. Write the text in Arabic script. |
| arb | Arabic — Modern Standard | News, formal narration and announcements. |
language is optional but improves pronunciation, especially for Arabic. Text direction is detected automatically in the studio.Voice design (instruct)
Instead of a cloned voice you can describe one. instruct is a comma-and-space separated list from the model’s fixed vocabulary; an unknown attribute returns 400 with the valid options.
{"text": "Good evening.", "instruct": "male, elderly, low pitch, british accent"}Common attributes: male / female, young / middle-aged / elderly, low pitch / high pitch, american / british / indian accent.
Errors & limits
| Status | Meaning | What to do |
|---|---|---|
| 401 | Missing or invalid API key | Send Authorization: Bearer <key>. |
| 400 | Bad instruct attribute / unreadable audio | Use vocabulary from the error message; upload WAV/FLAC/OGG. |
| 404 | Unknown voice_id | Register the voice again with /v1/voices (ids are deterministic). |
| 413 | Reference audio too large | Keep references under 50 MB (3–10 s is ideal). |
| 422 | Validation error | Check field types and the 20,000-character text limit. |
| 451 | Not available in your region | The service is offered in the UAE and India only. |
| 502 | Engine unavailable | Retry with backoff; check /health. |
Requests are processed on a single GPU behind a lock and serialize under load; real-time factor is ≈ 0.025, so a 60-second clip renders in about 1.5 seconds.
Browsers & regions
The studio is tested end to end on Chrome, Edge, Safari (macOS and iOS) and Firefox. Playback is handled per engine: progressive streaming on Chromium, buffered playback on WebKit and Gecko.
Voice Stack is available in the United Arab Emirates and India. Requests from other regions receive HTTP 451.
Support
Use the Feedbackbutton in the studio header to report a bug, suggest an idea or flag a voice that doesn’t sound right — messages go straight to the Xpin AI team. For API keys and workspace changes, contact your workspace admin.