Real-time Voice (Text-to-Speech)

VALSEA provides real-time Text-to-Speech over WebSocket for low-latency audio playback. Use this live endpoint when audio must begin streaming before the complete response is available. For single-request generation, use Batch Text-to-Speech.

Batch vs. Real-time TTS

Both modes generate speech from text and use the same stable VALSEA voice names. Batch TTS returns one complete audio response; Real-time TTS streams audio chunks as they are generated.

Mode	Endpoint	Model	Best for
Batch TTS	`POST /v1/audio/speech`	`valsea-tts`	Complete files and single-request generation
Real-time TTS	`WS /v1/realtime/tts`	`valsea-tts-realtime`	Conversational playback and low time-to-first-audio

Connection

Endpoint: wss://api.valsea.ai/v1/realtime/tts

Authenticate during the WebSocket handshake with one of these options:

Authorization: Bearer YOUR_API_KEY
X-API-Key: YOUR_API_KEY
Query parameter: api_key=YOUR_API_KEY

Message Flow

Connect to the WebSocket endpoint.
Receive session.created.
Send session.start with model, voice, language, and output options.
Receive session.ready.
Send speech.create with the text input.
Receive speech.started, then binary audio chunks, then speech.finished.
Send session.stop to close cleanly.

Client Messages

`session.start`

{
  "type": "session.start",
  "model": "valsea-tts-realtime",
  "language": "vietnamese",
  "voice": "valsea-neutral",
  "response_format": "mp3",
  "speed": 1,
  "normalization": "basic",
  "audio_quality": 64
}

Field	Type	Description
`model`	`valsea-tts-realtime`	Real-time TTS model.
`language`	string	A code from Supported Languages.
`voice`	a supported voice	Voice name for the selected language.
`response_format`	`mp3` \| `wav` \| `opus`	Binary audio chunk format.
`speed`	number \| `"default"`	Playback speed from `0.25` to `4`, or the preset default.
`stability`	number \| `"default"`	Arabic voice stability from `0` to `1`, or preset default.
`normalization`	`no` \| `basic` \| `advanced`	Text normalization level.
`audio_quality`	integer	Audio quality value. Default: `64`.

Supported Languages

Real-time TTS accepts vietnamese, english, english-in, hindi, bengali-in, kannada, malayalam, marathi, odia (also accepted as oriya), punjabi, tamil, telugu, gujarati, and arabic.

sinhala is currently available through Batch Text-to-Speech, not Real-time TTS.

Voices

Use valsea-neutral, valsea-male, or valsea-female for every supported language except Arabic. For language: "arabic", use one of these dedicated presets:

Voice	Description
`valsea-arabic-mid-female-emirati`	Mid-Female (Emirati)
`valsea-arabic-lively-female-emirati`	Lively-Female (Emirati)
`valsea-arabic-calm-male-emirati`	Calm-Male (Emirati)
`valsea-arabic-calm-mid-male-emirati`	Calm-Mid-Male (Emirati)

Each Arabic preset has tuned speed and stability defaults. Omit either field or use "default" to retain the preset value.

Arabic session

{
  "type": "session.start",
  "model": "valsea-tts-realtime",
  "language": "arabic",
  "voice": "valsea-arabic-mid-female-emirati",
  "speed": "default",
  "stability": "default"
}

`speech.create`

{
  "type": "speech.create",
  "input": "Xin chao, day la giong noi VALSEA."
}

`session.stop`

{ "type": "session.stop" }

Server Messages

`session.created`

{
  "type": "session.created",
  "sessionId": "tts_...",
  "supportedModels": ["valsea-tts-realtime"],
  "supportedVoices": ["valsea-neutral", "valsea-male", "valsea-female"],
  "supportedLanguages": [
    "vietnamese",
    "english",
    "english-in",
    "hindi",
    "bengali-in",
    "kannada",
    "malayalam",
    "marathi",
    "odia",
    "oriya",
    "punjabi",
    "tamil",
    "telugu",
    "gujarati",
    "arabic"
  ]
}

The supportedVoices value currently lists the three general-purpose aliases. Arabic sessions use one of the dedicated presets listed in Voices.

`session.ready`

{
  "type": "session.ready",
  "sessionId": "tts_...",
  "model": "valsea-tts-realtime"
}

Audio events

The server sends speech.started, then binary audio WebSocket frames, then speech.finished.

{ "type": "speech.started", "sessionId": "tts_..." }

{ "type": "speech.finished", "sessionId": "tts_..." }

Example

const WebSocket = require('ws');
const fs = require('fs');

const ws = new WebSocket('wss://api.valsea.ai/v1/realtime/tts', {
  headers: { Authorization: 'Bearer YOUR_API_KEY' },
});

const chunks = [];

ws.on('message', (data, isBinary) => {
  if (isBinary) {
    chunks.push(Buffer.from(data));
    return;
  }

  const message = JSON.parse(data.toString());

  if (message.type === 'session.created') {
    ws.send(
      JSON.stringify({
        type: 'session.start',
        model: 'valsea-tts-realtime',
        language: 'vietnamese',
        voice: 'valsea-neutral',
        response_format: 'mp3',
      }),
    );
  }

  if (message.type === 'session.ready') {
    ws.send(
      JSON.stringify({
        type: 'speech.create',
        input: 'Xin chao, day la giong noi VALSEA.',
      }),
    );
  }

  if (message.type === 'speech.finished') {
    fs.writeFileSync('speech.mp3', Buffer.concat(chunks));
    ws.send(JSON.stringify({ type: 'session.stop' }));
  }
});

Billing

Real-time TTS is billed by generated audio duration, rounded up to the next whole minute.