Hamsa API · Voice Cloning
Voice Cloning API
Turn an audio sample into a custom AI voice, then use it anywhere Hamsa speaks: the voice’s UUID is a speaker for the TTS APIs, the agents platform and the media studio. Create, preview, favourite and manage voices over REST.
- Arabic and English voices
- Upload or record a sample
- 7 audio formats, up to 35 MB
- Preview before you commit
- One voice ID everywhere
Capabilities
Custom voices as an API object
A voice from a sample
Provide clear recorded speech — uploaded or recorded directly — and the system builds a voice model from it. Sample quality decides voice quality.
Arabic with a dialect
A voice is created for a language, English or Arabic, and Arabic voices take a regional dialect — Egyptian, Jordanian, Saudi, Emirati, Gulf, Levantine or North African — so pronunciation stays native.
Described by tags
Each voice carries two tags, gender and style — conversational or narrator — so libraries of custom voices stay filterable as they grow.
Preview before use
Generate a TTS preview of the cloned voice and hear it before it goes anywhere near production.
Managed over REST
List, fetch, favourite and delete voices through the voices endpoints — the same catalog that backs the dashboard’s voice library.
Spoken everywhere
The cloned voice’s UUID works as the speaker on realtime TTS and the WebSocket, as a preloaded voiceId on TTS jobs, and as an agent voice.
Workflow
From recording to production voice
The life of a cloned voice, from sample to speaker.
- 01
Prepare the sample
Clear, noise-free speech at a natural pace, with varied sentences. MP3, WAV, WebM, OGG, AAC, M4A or FLAC, up to 35 MB.
- 02
Create the voice
Name it (up to 100 characters), set the language and — for Arabic — the dialect, pick its gender and style tags, and optionally add a description and cover image.
- 03
Let it process
The system analyses the sample and builds the voice model.
- 04
Preview and test
Generate test audio with the new voice and listen before adopting it.
- 05
Use the UUID as a speaker
Pass it to realtime TTS or the WebSocket directly; for the async jobs API, preload the voice once first. Agents select it like any library voice.
Reference
The voice cloning 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 |
|---|---|
| Create a voice | Build a custom voice from an uploaded or recorded sample |
| The library | List every voice, system and custom, with filtering and pagination |
| One voice | Fetch a voice, mark it as a favourite, or delete it |
| Preview | Generate test speech with a voice before adopting it |
| Dialects | The dialect codes a voice can take |
| Preload | Required once before a cloned voice is used on speech jobs |
| Sample formats | MP3, WAV, WebM, OGG, AAC, M4A, FLAC — up to 35 MB |
| Voice metadata | Name up to 100 characters; language; Arabic dialect; gender and style tags; optional description and cover image |
| Authentication | A secret key in the Authorization header of every request, as Token <key> |
Use cases
Where cloned voices earn their keep
A brand voice
One recognisable voice across your phone agents, media content and apps, instead of a different stock voice in each.
Narration at scale
Clone a narrator once and generate episodes, course material or voice-overs through the TTS APIs without booking studio time for each.
Dialect-true agents
An agent that speaks in a cloned voice with the right regional dialect sounds like it belongs to the market it serves.
Consistent product audio
Notifications, guides and in-app speech generated on demand, always in the same voice, from the same voice ID.
FAQ
Questions about voice cloning
What does the audio sample need to be?
+
Clear, noise-free speech recorded at a natural pace, ideally with varied sentence types. Upload MP3, WAV, WebM, OGG, AAC, M4A or FLAC up to 35 MB, or record directly. The quality of the sample decides the quality of the voice.
Which languages and dialects can a cloned voice have?
+
English or Arabic. Arabic voices take a regional dialect — Egyptian, Jordanian, Saudi, Emirati, Gulf, Levantine or North African — which shapes pronunciation and natural speech patterns. English voices need no dialect.
How many custom voices can I create?
+
There is no fixed cap on custom voices. Tags — gender plus conversational or narrator style — keep a growing library organised and filterable.
How do I use a cloned voice in the TTS APIs?
+
Pass the voice’s UUID as the speaker on the realtime endpoint or the WebSocket. For the async jobs API, call the preload endpoint for the voice once, then use the UUID as the voiceId.
Can I hear a cloned voice before using it?
+
Yes. The preview endpoint generates test speech with the voice, and the dashboard plays previews from every voice card, so a voice is heard before it is adopted.
Keep reading
Hamsa API · Text to Speech
Arabic Text to Speech API
Synchronous, async and streaming Arabic speech generation in 14 dialects plus English, with telephony output and cloned voices.
Read →Hamsa Media · API
Media Platform API
Transcription, text-to-speech and AI content as async jobs over REST, with webhook delivery and full job management.
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 →


