Voice Stack by Xpin AI

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

Studio

A browser workspace: write, pick a voice, listen, download. History is saved to your account.

API

POST text, get a 24 kHz WAV — or stream it over HTTP / WebSocket with first audio in ~0.4 s.

Voices

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.

  1. 1Get an API key from your Xpin AI admin (keys are issued per workspace).
  2. 2Send text to /v1/tts.
  3. 3Play or save the WAV.
curl
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.wav
Studio guide

Text 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.

ControlWhat it does
VoiceAny library voice or one of your clones. Cloned voices reproduce the reference speaker; catalogue voices are designed from gender / age / accent.
ModelRealtime streams audio while later sentences are still rendering (best for previews). Studio renders the whole file first (best for long scripts and downloads).
LanguageEnglish or Arabic (Emirati). Arabic text is written right-to-left automatically; the quick-start chips set the language for you.
Speed50–150 %. 100 % is the natural pace of the voice.
Stability / Similarity / StyleDelivery hints for designed voices. Cloned voices follow the reference recording.
Tip: punctuation drives pacing. Ellipses add pauses, commas add breath, and ALL CAPS adds emphasis.

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.

API reference

Base URL & authentication

base url
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.

headers
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.

JavaScript (fetch)
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/wav
Python (requests)
import 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 (play as it arrives)
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 -
Browser tip: Chrome plays the stream progressively from an <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.

FramePayload
→ text{"text": "...", "voice_id": "v_…", "language": "en"}
← start{"type":"start","sample_rate":24000,"format":"pcm_s16le","channels":1}
← binary ×NRaw 16-bit little-endian PCM, one frame per text chunk
← end{"type":"end","chunks":N,"duration_s":…}
← error{"type":"error","message":"…"}
JavaScript (browser)
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
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

FieldTypeDefaultNotes
textstringrequiredUp to 20,000 characters.
voice_idstring"default"Id returned by /v1/voices. Omit for the default voice.
languagestringautoen, afb (Emirati), arb (Standard Arabic) — see Languages.
instructstring—Voice-design attributes; overrides voice_id. See Voice design.
speednumber1.00.25 < speed < 4.0. >1 faster, <1 slower.
normalize_textbooleanfalseSpeak numbers, dates and currency as words.
chunk_charsinteger200Streaming only: target characters per chunk (20–1000).

Languages

Pass either the ISO 639-3 code or the lowercase English name. Voice Stack currently offers:

CodeLanguageNotes
enEnglishAll accents; catalogue voices default to American.
afbArabic — Emirati / GulfUse for Emirati and Saudi Gulf speech. Write the text in Arabic script.
arbArabic — Modern StandardNews, formal narration and announcements.
Setting 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.

example
{"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

StatusMeaningWhat to do
401Missing or invalid API keySend Authorization: Bearer <key>.
400Bad instruct attribute / unreadable audioUse vocabulary from the error message; upload WAV/FLAC/OGG.
404Unknown voice_idRegister the voice again with /v1/voices (ids are deterministic).
413Reference audio too largeKeep references under 50 MB (3–10 s is ideal).
422Validation errorCheck field types and the 20,000-character text limit.
451Not available in your regionThe service is offered in the UAE and India only.
502Engine unavailableRetry 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.

Good to know

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.