Skip to main content
WSS
wss://api.tryhamsa.com/v1/realtime/ws
Messages
api_key
type:httpApiKey

API key passed as query parameter or X-Api-Key header

TTS Request
type:object

Request to convert text to speech

TTS Acknowledgment
type:object

Server acknowledges the TTS request

TTS Audio Chunk
type:string

Binary audio data chunk

TTS Stream End
type:object

Signals the end of the audio stream

Error Response
type:object

Error message from the server

Connect to the WebSocket and send TTS requests to convert text into streaming audio.

​
Quick Start

  1. Enter your API key in the authentication field
  2. Click Connect to establish the WebSocket connection
  3. Modify the request payload with your text
  4. Click Send to receive streaming audio

​
Request Message

After connecting, send a JSON message with the following structure:
​
type
string
required
Must be "tts"
​
payload
object
required
TTS Request
{
  "type": "tts",
  "payload": {
    "text": "مرحبا بك في خدمة همسة",
    "speaker": "speaker-1",
    "dialect": "modern",
    "languageId": "ar",
    "mulaw": false
  }
}

​
Response Sequence

The server responds with:
1. Acknowledgment
{
  "type": "ack",
  "payload": {
    "message": "Real time text to speach connection establesh"
  }
}
2. Binary Audio Chunks
// Raw binary audio data streamed in chunks
// Buffer these chunks to reconstruct the complete audio
3. Stream End
{
  "type": "end",
  "payload": {
    "message": "End of TTS stream"
  }
}

​
Available Speakers

Refer to Hamsa Platforms to get the list of the available pre-built speakers where you can take the name of the speaker, or use a UUID for your custom cloned voice.

​
Using Custom Cloned Voices

When using a custom cloned voice (UUID) as the speaker, you must preload the voice before establishing the WebSocket connection. This ensures optimal latency during streaming.
Preload Required for Custom VoicesCall the Preload Voice endpoint once when your application starts to avoid latency when using custom cloned voices.
// 1. Preload the custom voice at app startup
await fetch('https://api.tryhamsa.com/v2/tts/voices/custom/preload', {
  method: 'POST',
  headers: {
    'Authorization': 'Token YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ voiceId: 'your-custom-voice-uuid' })
});

// 2. Now connect to WebSocket and use the custom voice
const ws = new WebSocket('wss://api.tryhamsa.com/v1/realtime/ws?api_key=YOUR_API_KEY');

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: 'tts',
    payload: {
      text: 'Hello from my custom voice',
      speaker: 'your-custom-voice-uuid', // Use the same UUID
      dialect: 'modern',
      languageId: 'ar',
      mulaw: false
    }
  }));
};