Skip to main content

​
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

​
Realtime TTS (synchronous)

Returns audio directly in the response. 
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 -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

ParameterTypeRequiredDescription
textstringYesThe text to convert to speech
speakerstringYesVoice name (e.g., “Amjad”, “Layan”) or UUID of a cloned voice
dialectstringNoDialect code (e.g., pls, egy, ksa) — see supported dialects
mulawbooleanNoUse μ-law encoding for telephony (default: false)

​
Jobs API

ParameterTypeRequiredDescription
textstringYesThe text to convert to speech
voiceIdstringYesVoice ID to use. For cloned voices, preload first
webhookUrlstringNoURL to receive the completed job result
webhookAuthobjectNoAuthentication for the webhook

​
Supported dialects

CodeDialectExample voices
plsPalestinianAmjad, Layan
egyEgyptianMariam, Samir
syrSyrianDalal, Mais
irqIraqiLyali, Fatma
jorJordanianLana, Jasem
lebLebaneseCarla, Majd
ksaSaudiHiba, Fahd
uaeEmiratiSalma, Dima
bahBahrainiMazen, Ruba
qatQatariDeema, Faisal
kuwKuwaitiMai, Hatem
omaOmaniAisha, Jaber
msaModern Standard ArabicSalem, Tamim
ar-saArabic – GulfKhalid, Rahma
enEnglishEmma, James