Quickstart

Convert text into lifelike speech

Text to Speech Quickstart

Hamsa offers two TTS endpoints:

• Jobs API (/v1/jobs/text-to-speech) — Async job-based. Returns a job ID; audio is delivered via webhook or polling.
• Realtime API (/v1/realtime/tts) — Synchronous. Returns a WAV audio file directly.

Prerequisites

• Hamsa API Key

Realtime TTS (synchronous)

Returns audio directly in the response.

cURL

curl -X POST https://api.tryhamsa.com/v1/realtime/tts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "أهلاً و سهلاً بكم في همسة!",
    "speaker": "Amjad",
    "dialect": "pls"
  }' \
  --output speech.wav

Jobs API (async)

Initiates a TTS job. The result is delivered via webhook or can be polled.

cURL

curl -X POST https://api.tryhamsa.com/v1/jobs/text-to-speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "أهلاً و سهلاً بكم في همسة!",
    "voiceId": "Amjad",
    "webhookUrl": "https://your-server.com/webhook"
  }'

Parameters

Realtime API

Parameter	Type	Required	Description
text	string	Yes	The text to convert to speech
speaker	string	Yes	Voice name (e.g., “Amjad”, “Layan”) or UUID of a cloned voice
dialect	string	No	Dialect code (e.g., pls, egy, ksa) — see supported dialects
mulaw	boolean	No	Use μ-law encoding for telephony (default: false)

Jobs API

Parameter	Type	Required	Description
text	string	Yes	The text to convert to speech
voiceId	string	Yes	Voice ID to use. For cloned voices, preload first
webhookUrl	string	No	URL to receive the completed job result
webhookAuth	object	No	Authentication for the webhook

Supported dialects

Code	Dialect	Example voices
pls	Palestinian	Amjad, Layan
egy	Egyptian	Mariam, Samir
syr	Syrian	Dalal, Mais
irq	Iraqi	Lyali, Fatma
jor	Jordanian	Lana, Jasem
leb	Lebanese	Carla, Majd
ksa	Saudi	Hiba, Fahd
uae	Emirati	Salma, Dima
bah	Bahraini	Mazen, Ruba
qat	Qatari	Deema, Faisal
kuw	Kuwaiti	Mai, Hatem
oma	Omani	Aisha, Jaber
msa	Modern Standard Arabic	Salem, Tamim
ar-sa	Arabic – Gulf	Khalid, Rahma
en	English	Emma, James