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

01

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.

02

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.

03

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.

04

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.

05

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.

06

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.

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

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

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

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

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

ItemDetail
Instant speechText, speaker and dialect in; WAV audio straight back in the response
Speech jobsQueued generation, delivered to your webhook or fetched by job ID
StreamingAudio streamed over a persistent WebSocket as it is generated; up to 2,000 characters per request
Dialects14 Arabic dialects — from Egyptian and Saudi to Modern Standard Arabic — plus English
OutputWAV; PCM at 8k or 16k sample rate; μ-law at 8 kHz for telephony
ExpressivenessFrom flat and monotone to highly expressive, on a 0–2 scale
Cloned voicesThe voice’s UUID as the speaker on instant and streaming calls; preloaded once for jobs
AuthenticationA secret key in the Authorization header of every request, as Token <key>

Use cases

What teams build on the TTS API

01

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.

02

Media and voice-over

The jobs API turns scripts into narrated audio in the dialect of the audience, delivered to your pipeline by webhook.

03

In-app speech

The synchronous endpoint gives mobile and web apps spoken responses with a single request-response round trip.

04

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

Partner ecosystem

Trusted Across the
Technology Ecosystem

Hamsa works with leading technology companies, integrators, and solution providers to bring enterprise Voice AI to organizations across the region.