Skip to main content

​
Overview

UneeQ is a digital human platform that can use a custom voice service for text-to-speech synthesis. This guide explains how to connect UneeQ to Hamsa’s real-time TTS engine so your digital human speaks with a Hamsa voice. Hamsa exposes a dedicated endpoint that speaks the UneeQ custom voice protocol — UneeQ calls it directly, passing your Hamsa API key and the desired voice preset, and receives a raw PCM audio stream in response.

​
How It Works

1

Configure UneeQ

In your UneeQ experience settings, set the custom voice endpoint URL and provide your Hamsa API key.
2

UneeQ sends a TTS request

When the digital human needs to speak, UneeQ sends a POST request to your endpoint with the text and the voice preset name.
3

Hamsa synthesises speech

Hamsa validates the API key, generates the audio using the requested voice, and streams back raw PCM audio.
4

UneeQ plays the audio

UneeQ receives the binary stream and drives the digital human’s lip sync and speech in real time.

​
Endpoint

POST https://api.tryhamsa.com/v1/realtime/uneeq/tts

​
Authentication

Unlike other Hamsa endpoints, this one does not use an Authorization header. UneeQ sends the API key inside the JSON request body, so no extra headers are required on your side.
Keep your Hamsa API key secret. Anyone who has it can make TTS requests that will be billed against your account.

​
Request Body

{
  "apiKey": "<your-hamsa-api-key>",
  "preset": "<hamsa-speaker-name>",
  "text": "<text to speak>"
}
FieldTypeRequiredDescription
apiKeystringYesYour Hamsa API key
presetstringYesHamsa speaker name to use as the voice (e.g. Amjad, Salma)
textstringYesText to synthesise. Maximum 2000 characters

​
Response

On success the endpoint returns a chunked binary stream of raw PCM audio with the following properties:
ParameterValue
HTTP Status200 OK
Content-Typeapplication/octet-stream
Sample Rate16 kHz
ChannelsMono
Encoding16-bit signed integers
Byte OrderLittle-endian
FormatRaw PCM — no WAV headers or compression
These audio specs match UneeQ’s custom voice requirements exactly. No conversion is needed on your end.

​
Error Responses

StatusMeaning
400Validation error — check that all required fields are present and text is under 2000 characters
401Invalid or missing API key
402Insufficient wallet balance
429Rate limit exceeded (100 requests/minute per API key)
503TTS service temporarily unavailable

​
Available Voices (Presets)

Pass any Hamsa speaker name as the preset value. You can find the full list of available voices in the Voice Library on the dashboard. Some examples:
PresetDescription
AmjadMale, Modern Standard Arabic
SalmaFemale, Egyptian dialect
LyaliFemale, Levantine dialect
JasemMale, Gulf dialect
The preset value maps directly to Hamsa’s speaker names. The language is Arabic (ar) by default. If you need a different dialect, contact support to discuss configuration options.

​
Setting Up in UneeQ

1

Open your UneeQ experience

Go to the UneeQ Creator and open the experience you want to configure.
2

Navigate to Voice settings

Go to Settings → Voice → Custom Voice.
3

Set the endpoint URL

Enter:
https://api.tryhamsa.com/v1/realtime/uneeq/tts
4

Set the API key

Paste your Hamsa API key into the API Key field. UneeQ will include it as apiKey in every request body automatically.
5

Set the voice preset

Enter the Hamsa speaker name (e.g. Amjad) in the Preset / Voice field.
6

Save and test

Save the configuration and use UneeQ’s built-in voice preview to confirm the integration is working.

​
Example Request

This is what UneeQ sends to the endpoint behind the scenes: 
curl -X POST https://api.tryhamsa.com/v1/realtime/uneeq/tts \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "your-hamsa-api-key",
    "preset": "Amjad",
    "text": "مرحباً، كيف يمكنني مساعدتك اليوم؟"
  }' \
  --output audio.pcm

​
Support

Contact Support

Get help from our technical team

UneeQ Custom Voice Docs

UneeQ’s official custom voice integration guide