Hamsa API · Text to Speech
Arabic Text to Speech API
One voice engine behind three endpoints: a synchronous call that returns WAV audio directly, an async jobs API for longer work, and a WebSocket that streams audio as it is generated. Voices span 14 Arabic dialects and English, including voices you clone yourself.
- 14 Arabic dialects + English
- Sync, async and streaming
- WAV, PCM 8k/16k, μ-law
- Expressiveness control
- Cloned voices as speakers
Capabilities
A speech API built for Arabic first
Dialect by parameter
Pass a dialect code — egy, ksa, pls, msa and eleven more — and a matching voice, and the output speaks that dialect, not a generic Arabic.
Audio in the response
The synchronous endpoint returns a WAV file directly: one POST with text, speaker and dialect, and the reply is the audio itself.
Jobs for longer work
The async endpoint queues the generation and delivers the result to your webhook, with optional webhook authentication, or you poll the job.
Streaming over WebSocket
One persistent connection takes TTS requests up to 2,000 characters each and streams audio back as it is generated — the same socket also serves STT.
Telephony-ready output
Set mulaw for 8 kHz μ-law audio that drops straight into phone systems, or choose PCM at 8k or 16k for everything else.
Your own voices
A cloned voice is a speaker like any other: pass its UUID to the realtime endpoint, or preload it once for the jobs API.
Integration
From text to audio
What a TTS integration looks like, request by request.
- 01
Create a secret key
Create a secret key in the dashboard and keep it on your server. Every request carries it in the Authorization header as Token <key>.
- 02
Pick a voice and dialect
Choose from the voice catalog — each dialect has named voices, like Amjad for Palestinian or Hiba for Saudi — or use the UUID of a voice you cloned.
- 03
Choose sync, async or streaming
The realtime endpoint returns WAV in the response. The jobs endpoint delivers by webhook. The WebSocket streams chunks as they are generated.
- 04
Shape the audio
Set expressiveness from 0 (flat) to 2 (highly expressive), and pick the output: PCM at 8k or 16k, or μ-law for telephony.
- 05
Play or store the result
Synchronous and streaming audio can play as it arrives; job results land on your server, ready to serve or post-process.
Reference
The Text to Speech API at a glance
Each row links to its page in the API docs — the authoritative reference, with full schemas and runnable code samples.
| Item | Detail |
|---|---|
| Instant speech | Text, speaker and dialect in; WAV audio straight back in the response |
| Speech jobs | Queued generation, delivered to your webhook or fetched by job ID |
| Streaming | Audio streamed over a persistent WebSocket as it is generated; up to 2,000 characters per request |
| Dialects | 14 Arabic dialects — from Egyptian and Saudi to Modern Standard Arabic — plus English |
| Output | WAV; PCM at 8k or 16k sample rate; μ-law at 8 kHz for telephony |
| Expressiveness | From flat and monotone to highly expressive, on a 0–2 scale |
| Cloned voices | The voice’s UUID as the speaker on instant and streaming calls; preloaded once for jobs |
| Authentication | A secret key in the Authorization header of every request, as Token <key> |
Use cases
What teams build on the TTS API
Voice agents and IVR
μ-law output at 8 kHz feeds phone systems directly, and streaming keeps the agent speaking while the rest of the reply is still generating.
Media and voice-over
The jobs API turns scripts into narrated audio in the dialect of the audience, delivered to your pipeline by webhook.
In-app speech
The synchronous endpoint gives mobile and web apps spoken responses with a single request-response round trip.
Branded voices at scale
Clone a voice once, then use its UUID anywhere the API takes a speaker — the same voice across your agents, media and apps.
FAQ
Questions about the Text to Speech API
Which Arabic dialects does the API speak?
+
Fourteen dialect codes: Palestinian, Egyptian, Syrian, Iraqi, Jordanian, Lebanese, Saudi, Emirati, Bahraini, Qatari, Kuwaiti, Omani, Modern Standard Arabic and Gulf Arabic — plus English. Each dialect has named voices, and the dialect is a request parameter, not a separate product.
When do I use the realtime endpoint versus the jobs API?
+
The realtime endpoint returns WAV audio in the response, which suits interactive features that need the audio now. The jobs API queues the work and delivers by webhook, which suits longer content and batch generation. For audio that should start playing before generation finishes, use the WebSocket.
Can the output feed a phone system?
+
Yes. Set mulaw to true and the audio comes back as 8 kHz μ-law, the encoding telephony expects. Note that mulaw cannot be combined with the sampleRate option — μ-law output is always 8 kHz.
How do I use a cloned voice through the API?
+
On the realtime endpoint and the WebSocket, pass the cloned voice’s UUID as the speaker. On the jobs API, call the preload endpoint for the voice once, then use it as the voiceId.
Can I control how expressive the speech sounds?
+
Yes. The expressiveness parameter runs from 0, flat and monotone, to 2, highly expressive, with 1 as the default.
Keep reading
Hamsa API · Speech to Text
Arabic Speech to Text API
Batch, synchronous and WebSocket transcription of Arabic across dialects, with word timestamps, diarization and SRT export.
Read →Hamsa API · Voice Cloning
Voice Cloning API
Custom Arabic and English voices from your audio samples, created, previewed and managed over REST, usable across TTS, agents and media.
Read →Hamsa Agents · API
AI Phone Agents API
Create agents, connect numbers, start calls, run campaigns and read every conversation over REST, with webhooks for live call events.
Read →


